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 modelsfor listing available models
Structs§
- Chat
Context - Assembled context for a chat invocation.
- Invoke
Result - Result of an agent invocation, including response text and token usage.
- Memory
Entry - Memory entry parsed from an agent response.
- Model
Spec - Parsed model specification from
/modelcommand. - Parsed
Response - Parsed agent response metadata.
Enums§
- Control
Command - 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 asorch task addororch 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
--outputwrites 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 throughinvoke_agent, whose context can hold text anyone can write - invoke_
agent_ with_ session - Invoke an agent one-shot with
--session-idor--resumefor 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_TOOLSand 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.