Many of these terms come up across this guide. The codebase isn’t always consistent in naming; this page is the canonical reference.

​
Identifiers

Orion’s session_index.id. The UI/sidebar identifier shown in the sessions list. Used for fork/merge lineage (parent_session_id), cross-table joins, and the active-session state. Generated as a UUID at session creation.
Claude SDK’s session UUID. Stored as sdkSessionId in Orion’s DB — separate column from session_index.id. Used for SDK resume (projects/<conversationId>/ on disk) and as the cache key for Pi’s AgentSession (in-memory map keyed by conversationId).sessionId ≠ conversationId. They map 1:1 today but they are conceptually different identifiers. The handoff finding “Pi maps conversationId to disk-backed SessionManager files” refers to conversationId.
Storage column name in Orion’s session_index table for the SDK’s conversationId. Used during resume to pass back to query({ resume: sdkSessionId }).
User identity. Stored in auth Mutex in Rust and forwarded as env var to subprocesses. See env-var-forwarding.md for why this is a Mutex+env pair.
For nested subagents, the conversationId of the top-level conversation (not the immediate parent). Used by SubagentJsonlWriter for the path <vault>/.orion/subagent-events/<rootConversationId>/events.jsonl.
toolUseId: the id of a tool_use block emitted by an agent. parentToolUseId: when an agent spawns a subagent via Task (Claude) or spawn_subagent (Pi), the subagent’s events carry the parent’s toolUseId so the frontend can nest them correctly.

​
Engines

The Claude Agent SDK 0.2.76 — Anthropic’s official agent framework. Runs as a spawned child process (sdk-runner.mjs → SDK internally spawns cli.js). Communicates with the sidecar via stdin/stdout JSON-line.
Orion’s alternate agent runtime. Runs in-process within the sidecar via piAgentQuery(). Built on @mariozechner/pi-coding-agent. Supports OpenAI, Google, OpenRouter, Anthropic-via-Pi, and other providers.
The function at model-router.mjs:23-54 that parses a model string into {engine, provider, model}. Decides which engine handles a turn.
The function at model-router.mjs:96-123 — returns true for openai, openai-codex, azure-openai-responses providers. Gates Pi’s MCP proxy mode vs legacy bridged mode.
Pi runtime’s in-memory session object. Cached per conversationId in handler.mjs. Reused on follow-up turns to skip setup phase. See GAP-A1 for the frozen-prompt implication.

​
MCP & permissions

Set of MCP server names auto-trusted in the Claude SDK canUseTool closure. Populated by trackingCreateServer() for the 5 internal servers (orion, orion-tools, canvas, terminal, codexlens) plus any plugin-namespaced servers.
Process-level trust list at config/constants.mjs:7-12. Values: ['shadcn', 'docs', 'claude-code-docs', 'orion']. Separate from internalServers — these are “permanently trusted” regardless of per-query state.
Pi MCP execution mode for OpenAI Responses-API providers. Instead of registering each internal MCP tool as mcp__server__tool Pi ToolDefinitions, registers a single mcp proxy tool that brokers search → describe → call against InternalMcpManager + CombinedMcpManager.
Pi MCP execution for non-OpenAI providers. Each internal MCP tool is bridged as a Pi ToolDefinition named mcp__server__tool. The 37-tool surface.
Pi sandbox path-policy hard-block list at policy-loader.mjs:82-127. User cannot remove built-ins. Includes .env, *.pem, **/.ssh/**, **/.aws/**, **/orion.db, **/.orion/mcp-oauth/**, etc.
Function at canUseTool.mjs:81-100 that queries the mcp_tool_permissions DB table for user-configured block/allow/ask. Only called on Claude SDK path, not Pi — see GAP-B1.

​
Canvas

CanvasMode is a string union for file-backed surfaces: document, plaintext, code, spreadsheet, pdf, htmlpreview, presentation, fallback. widget is also in the union — but conceptually different: it’s the widget track, activated by setWidget() not by openFile(). Mutually exclusive: setting one clears the other.
JSON-render flat-format spec for canvas widgets. Type re-exported from @json-render/core: { root: string; elements: Record<string, UIElement> }. The “flat” format means children are referenced by id, not nested.
orionCatalog is the Zod-typed component catalog at widget-catalog.ts. orionRegistry is the runtime wiring of catalog → React components at registry/index.ts. The catalog feeds catalog.prompt() (system prompt for AI); the registry feeds <Renderer registry={...}/>.
The component at src/components/canvas/editors/WidgetCanvas.tsx that renders a widget spec via @json-render/react’s Renderer against orionRegistry. Used when mode === 'widget'.
Two extension lists in canvas file routing. EXTENSION_MAP (file-router.ts:20-75) maps known extensions to a CanvasMode. DIRECT_OPEN_EXTENSIONS (constants.ts:19-28) are binary formats that bypass canvas entirely and open in the system default app via shell.open().

​
Background work

Cron execution mode (payload.executionMode === 'recipe') that forces Claude SDK regardless of payload.model. Used for legacy Composio recipe execution. Setting model: 'google/gemini-2.5-flash' on a recipe job is silently overridden.
Background workflow with explicit AI-WITH-YOU gate enforcement. Three-table model: autopilots (what), autopilot_triggers (when), autopilot_runs (proposal+run). Three-layer enforcement (DDL CHECK + runtime JS branch + Rust command guard) on acceptance_mode: 'suggest' | 'auto'.
Column on autopilots table. 'suggest' (default) → autopilot fires create proposals only; user must accept. 'auto' → autopilot fires create para_tasks atomically without user prompt. 'auto' requires explicit_user_opt_in=true at create time (Rust guard).
Constants at config/constants.mjs:80-97. Five keys: heartbeat_model, enrichment_model, consolidation_model, dream_model, cron_default_model. Defaults Pi (Gemini Flash), fallbacks Claude Haiku.
Function at lib/preferences.mjs:69. Three-tier resolution: payload.model → user_preferences[key] → BACKGROUND_MODEL_DEFAULTS[key].
Two MCP tools on mcp__orion-tools that spawn external CLIs (Gemini, Codex, Claude CLI, Qwen, opencode). delegate_to_cli is fire-and-forget (returns delegation id immediately). execute_cli_inprocess blocks until CLI exits. Neither applies OS sandboxing — see GAP-D1.

​
Agents & subagents

Folder per agent: <dir>/<slug>/AGENTS.md (required) + config.yaml (required) + SOUL.md (optional persona) + MEMORY.md (optional seed memory). Two layers: bundle (prompts/agents/<slug>/) and vault (<vault>/agents/<slug>/). Vault overrides bundle.
Invariant: when an agent is dispatched as a subagent (Pi spawn_subagent or Claude Agent/Task), the body sent to the model is AGENTS.md only. SOUL.md and MEMORY.md are stripped. Enforced via getAgentDefForSubagent in agents/loader.mjs. Top-level chat sessions get the full bootstrap.
The agents SQLite table is a query-time index derived from config.yaml files. Boot reconcile (initLoader) and auth-change re-populate it via INSERT OR REPLACE. CRUD writes round-trip through config.yaml. The filesystem folder is authoritative; the DB is rebuildable.
Pi’s subagent dispatch tool. Three modes: single / chain / parallel. Depth-guarded via _depthMap. Model fallback loop. See Subagents.

​
PARA & vault

Filesystem layout for user content: Projects/ (active work with deadlines), Areas/ (ongoing responsibilities), Resources/ (reference material), Archive/ (completed/inactive), Inbox/ (unprocessed capture). All five are uppercase on disk. See vault-directory-conventions.md.
~/Orion/vaults/<firebase_uid>/. Per-user content directory. Travels with backup/sync. Contains PARA dirs + .orion/ (per-user app data) + agents/ (user agents) + skills/ (user skills) + .git/ (SDK isolation boundary).
Per-user Orion-runtime artifacts inside the vault. Contents: mcp-oauth/, subagent-events/, memory/, ccw/, agents/.migrated, etc. Auto-created on first write.
macOS: ~/Library/Application Support/com.orion.butler/. App-managed data (not user-owned vault content). Per-user profile DB lives at profiles/<firebase_uid>/orion.db. Sidecar sessions at pi-sessions/, sdk-sessions/, etc.

​
IPC

The Rust enum (and TypeScript union) defining the IPC contract between sidecar and frontend. Always camelCase. 18+ variants: text, thinking, toolStart, toolComplete, complete, error, pong, usageUpdate, subagentStart, subagentComplete, etc. See Event Layer.
All IPC event type values are camelCase. Mismatch (e.g., tool_start instead of toolStart) causes Rust serde to fail with unknown variant. See sdk-ipc-naming-convention.md.
The factory at canUseTool.mjs. createCanUseTool(ctx) returns a closure-bound permission function per query. Three modes: default / bypassPermissions / plan.