plexus.cli.procedure.lua_dsl.primitives.session module

Session Primitive - Conversation history management.

Provides: - Session.append(role, content) - Add message to conversation - Session.inject_system(text) - Inject system message - Session.clear() - Clear conversation history - Session.history() - Get all messages as Lua table - Session.save() - Persist current session to database

class plexus.cli.procedure.lua_dsl.primitives.session.SessionPrimitive(chat_recorder, execution_context, lua_sandbox=None)

Bases: object

Manages agent conversation history for procedures.

Enables workflows to: - Manipulate conversation context - Inject system messages - Clear history for fresh contexts - Retrieve conversation for inspection

Initialize Session primitive.

Args:

chat_recorder: ProcedureChatRecorder for database operations execution_context: ExecutionContext for agent state access lua_sandbox: LuaSandbox for creating Lua tables (optional)

__init__(chat_recorder, execution_context, lua_sandbox=None)

Initialize Session primitive.

Args:

chat_recorder: ProcedureChatRecorder for database operations execution_context: ExecutionContext for agent state access lua_sandbox: LuaSandbox for creating Lua tables (optional)

append(role: str, content: str, metadata: Dict[str, Any] | None = None) → None

Add message to conversation history (in-memory only until save()).

Args:

role: Message role (USER, ASSISTANT, SYSTEM) content: Message content metadata: Optional metadata dict

Example (Lua):

Session.append(“USER”, “What is the weather?”) Session.append(“ASSISTANT”, “I need more information about location.”)

clear() → None

Clear conversation history (in-memory only until save()).

Example (Lua):

Session.clear() Session.inject_system(“Fresh context”)

count() → int

Get count of messages in session.

Returns:

Number of messages

Example (Lua):

local msg_count = Session.count() Log.info(“Messages in session”, {count = msg_count})

history()

Get all messages in conversation history.

Returns:

Lua table with messages (1-indexed for Lua)

Example (Lua):

local messages = Session.history() for i, msg in ipairs(messages) do

Log.info(“Message”, {

role = msg.role, content = msg.content

})

end

inject_system(text: str) → None

Inject system message into conversation.

This is a convenience method for Session.append(“SYSTEM”, text)

Args:

text: System message content

Example (Lua):

Session.inject_system(“Focus on security implications”)

load_from_node(node: Any) → int

Load conversation history from a graph node’s metadata.

Args:

node: Node dict with ‘id’ field (and optionally ‘metadata’)

Returns:

Number of messages loaded

Example (Lua):

local checkpoint = GraphNode.root() if checkpoint then

local count = Session.load_from_node(checkpoint) Log.info(“Resumed session”, {messages = count})

end

async save() → None

Persist current in-memory messages to database.

This records all queued messages via the chat recorder. Called automatically by runtime after workflow execution.

Example (Lua):

– Not typically called from Lua - runtime handles this

save_to_node(node: Any) → bool

Save conversation history to a graph node’s metadata.

Args:

node: Node dict with ‘id’ field

Returns:

True if saved successfully, False otherwise

Example (Lua):

Session.append(“ASSISTANT”, “Phase 1 complete”)

local checkpoint = GraphNode.create(“checkpoint”) Session.save_to_node(checkpoint) Log.info(“Session saved”, {node = checkpoint.id})