Skip to main content

Module control

Module control 

Source
Expand description

Control session — context assembly, one-shot agent invocation, response parsing.

The control session provides an interactive ops assistant that assembles context from SQLite (memories, summaries, live state), invokes an agent CLI one-shot with --session-id for conversation continuity, and parses the response for summary extraction.

§Session continuity

Each named session (e.g., “default”, “ops”) gets a UUID stored in SQLite KV (control:session_id:{name}). Session agents (claude, kimi, minimax, grok) receive --session-id <uuid> so they resume prior conversation state. The UUID is regenerated when the agent or model changes.

§Model selection

/model <spec> where spec is:

  • agent:model — explicit agent + model (e.g., minimax:sonnet, opencode:minimax-m2.5-free)
  • model — infer agent from model name (e.g., sonnet → claude, gpt-4o → codex)

All agents: claude, codex, opencode, kimi, minimax, grok

  • kimi and minimax are claude-compatible wrappers (separate binaries in PATH)
  • opencode supports opencode models for listing available models

Structs§

ChatContext
Assembled context for a chat invocation.
InvokeResult
Result of an agent invocation, including response text and token usage.
MemoryEntry
Memory entry parsed from an agent response.
ModelSpec
Parsed model specification from /model command.
ParsedResponse
Parsed agent response metadata.

Enums§

ControlCommand
Parsed control command from the chat session.

Constants§

CONTROL_CHAT_TOOLS
What the control chat may run on a Claude-compatible agent: orch’s commands for looking at and moving tasks, and gh’s read commands. Not orch config, which prints secrets, nor the commands that create work, such as orch task add or orch plan, since issue text could have asked for it
PROJECT_CHAT_TOOLS
What a project chat agent may run: read and search the project, and orch’s read commands. Not git, whose --output writes a file

Functions§

assemble_context
Assemble the chat context from SQLite state and live system info.
get_agent
Get the current agent from KV, defaulting to "claude" when the key is absent. Returns an error if the store read fails.
get_current_spec
Get the current control session spec from KV.
get_model
Get the current model from KV, defaulting to the current agent’s configured model when the key is absent. Returns an error if the store read fails.
get_or_create_session_uuid
Get or create a session UUID for the given session name.
invoke_agent
Invoke an agent CLI one-shot and return structured result with token usage.
invoke_agent_unsandboxed
A one-shot agent call outside the chat sandbox, for a prompt that holds only the owner’s own text, such as orch commit’s diff or a plan to turn into a roadmap. A chat goes through invoke_agent, whose context can hold text anyone can write
invoke_agent_with_session
Invoke an agent one-shot with --session-id or --resume for conversation continuity.
invoke_project_chat
A project chat turn. The agent runs in the project folder inside sandbox-jail, which lets it write only its temp dir and hides the rest of the home and every credential, and it may run PROJECT_CHAT_TOOLS and nothing else. Its context holds issue text anyone can write
maybe_handle_control_command
Handle a control-session command if present.
parse_control_command
Parse a control-session command.
parse_model_spec
Parse a model spec string into agent + model.
parse_response
Parse an agent response, extracting optional <summary> and <memory> tags.
reset_session_uuid
Reset the session UUID so the next message starts a fresh conversation.
send_message
High-level entry point: process a user message and return the assistant response.
set_agent
Set the current agent in KV.
set_agent_spec
Set the current agent and its default model in KV.
set_model
Set the current model in KV.
set_model_spec
Set the current model and agent in KV.
validate_agent
Validate that an agent name is known and installed.
validate_model
Validate a model spec by running a quick test invocation.