@enderfga/claw-orchestrator 7.14.0 → 7.16.0

package/skills/references/sessions.md

@@ -1,15 +1,15 @@
 # Sessions
 
-Sessions are the core abstraction — persistent, multi-turn coding conversations backed by a CLI subprocess.
+Sessions are the core abstraction — persistent, multi-turn coding conversations backed by a coding CLI. `claude`, `codex-app`, `acp` and a persistent `custom` engine keep one process alive for the whole session; the one-shot engines (`codex`, `agy`, `grok`, `opencode`) start a process per send and resume their conversation by its id.
 
 ## Lifecycle
 
 ```
-start() → send() → send() → ... → stop()
-           ↑                          |
-           └── resume (7-day TTL) ────┘
+startSession() → sendMessage() → sendMessage() → ... → stopSession()
 ```
 
+A session that sits idle past the memory TTL is unloaded, and one whose server restarts is gone from memory. Both stay in the resume registry for 7 days, and `startSession()` with the same name resumes the conversation. `stopSession()` ends a session for good: it removes the registry entry too, so the same name later starts a new conversation. See [Session Persistence](#session-persistence).
+
 ### Starting a Session
 
 ```typescript
@@ -25,49 +25,58 @@ const info = await manager.startSession({
 });
 ```
 
+Starting a name that is already live returns that session's info unchanged. The number of live sessions is capped by `maxConcurrentSessions` (default 5; 32 under `clawo serve`).
+
 Key options:
 
-| Option               | Description                                                                                                                                                                                                |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `engine`             | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'grok'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md)                                                                     |
-| `model`              | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`) or full name                                                                                                                                   |
-| `permissionMode`     | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`)                                                                                            |
-| `effort`             | `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, `auto` — each engine clamps to its own ladder (see [Multi-Engine](./multi-engine.md))                                                                    |
-| `bare`               | Skip hooks, LSP, auto-memory, CLAUDE.md                                                                                                                                                                    |
-| `worktree`           | Run in isolated git worktree                                                                                                                                                                               |
-| `appendSystemPrompt` | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation |
+| Option               | Description                                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `engine`             | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'grok'`, `'opencode'`, `'acp'` (with `acpAgent`), or `'custom'` (with `customEngine`) — see [Multi-Engine](./multi-engine.md)                                                                                                                                                                                             |
+| `model`              | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`, `agy-flash`, `grok`) or full name. A non-Claude model on the `claude` engine goes through the [multi-model proxy](#multi-model-proxy)                                                                                                                                                                                   |
+| `permissionMode`     | `acceptEdits` (default), `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`)                                                                                                                                                                                                                                                           |
+| `effort`             | `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, `auto` (default) — each engine clamps to its own ladder (see [Multi-Engine](./multi-engine.md))                                                                                                                                                                                                                                   |
+| `sandboxMode`        | `read-only`, `workspace-write`, `danger-full-access`. `codex` and `codex-app` support all three (default `workspace-write`); `read-only` is enforced on `claude`, `agy`, `grok` and `opencode` through their own read-only modes; a custom engine must map it or the session refuses to start; an `acp` session refuses `read-only`, because the agent's tools run inside the agent |
+| `maxBudgetUsd`       | Spend cap in USD, checked before every send on every engine; once spend reaches it, further sends are refused                                                                                                                                                                                                                                                                       |
+| `bare`               | Claude Code: skip hooks, LSP, auto-memory, CLAUDE.md                                                                                                                                                                                                                                                                                                                                |
+| `worktree`           | Claude Code: run in an isolated git worktree                                                                                                                                                                                                                                                                                                                                        |
+| `appendSystemPrompt` | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation, as does `codex-app` on a new thread and an `acp` session on a new session                                                                                               |
 
 ### Sending Messages
 
 ```typescript
 const result = await manager.sendMessage('my-task', 'Fix the auth bug', {
   effort: 'high', // override effort for this message
-  plan: true, // enter plan mode
-  timeout: 600_000, // 10 min timeout
+  plan: true, // ask for a plan only (claude and persistent custom engines)
+  timeout: 600_000, // 10 min timeout (default 5 min)
   onChunk: (text) => process.stdout.write(text), // streaming
 });
 
 console.log(result.output);
 ```
 
+Sends to one session run one at a time: a second `sendMessage()` waits for the first to finish. `plan` puts a plan-only instruction in front of the message and leaves the permission mode unchanged; start the session with `sandboxMode: 'read-only'` to enforce it. The result carries `output`, the engine's resume id as `sessionId`, `error` when the engine reported the turn as failed, and `permissionDenials` / `images` when the turn had any.
+
+`SendOptions` also accepts `parentRunId`, `nodeKind` and `taskKind`, all stamped onto the turn's run ledger row ([observability.md](./observability.md)). `taskKind` is caller-declared and never inferred from the prompt.
+
 ### Session Persistence
 
-Sessions automatically persist to `~/.openclaw/claude-sessions.json`:
+A session is recorded in the resume registry, `~/.openclaw/claude-sessions.json` (the directory can be moved with `CLAWO_SESSIONS_DIR`), once its engine has reported a resume id:
 
-- **Memory TTL**: configurable (default 120 min) — idle sessions unloaded
-- **Disk TTL**: 7 days — sessions can be resumed after gateway restart
-- **Auto-resume**: `startSession` with the same name auto-resumes if a persisted session exists
+- **Memory TTL**: an idle session is unloaded after `sessionTtlMinutes` (default 120; 60 under `clawo serve`). Its registry entry stays.
+- **Disk TTL**: 7 days since the last activity.
+- **Auto-resume**: `startSession` with a registered name resumes that conversation, restoring its engine, model, working directory, `sandboxMode`, `autoCompactPercent` and `chrome`. Other options — permission mode, tool lists, system prompts — are not stored; pass them again.
+- **Not recorded**: sessions started with `noSessionPersistence`, and sessions whose engine has not reported a resume id yet.
 
 ### Session Resume & Fork
 
 ```typescript
-// Resume a specific Claude Code session
+// Resume a conversation by the engine's own id
 await manager.startSession({
   name: 'continued',
   resumeSessionId: 'abc123-session-id',
 });
 
-// Fork for experiments (preserves history, new branch)
+// Claude Code and Grok: fork it for experiments (preserves history, new branch)
 await manager.startSession({
   name: 'experiment',
   resumeSessionId: 'abc123',
@@ -75,6 +84,8 @@ await manager.startSession({
 });
 ```
 
+`resumeSessionId` is the id the engine itself uses: a Claude Code session id, a Codex or `codex-app` thread id, an Antigravity conversation id, a Grok or OpenCode session id, an ACP agent's session id, or a custom engine's id when its config maps a resume flag. `forkSession` becomes `--fork-session` on Claude Code and Grok; it is a `SessionManager` option and not a `session_start` tool parameter.
+
 > `claude continue/respawn/stop/logs` are not headless subcommands — session continuation is via `resumeSessionId`/`forkSession`. Use the `claude_agents_list` tool (`claude agents --json`) to enumerate Claude Code background agent sessions.
 
 ### Handing off to another engine
@@ -91,6 +102,11 @@ await manager.handoffSession('refactor', {
 // → new session 'refactor-codex', same cwd; 'refactor' keeps running untouched
 ```
 
+`newName` names the new session (default `<name>-<engine>`) and `model` picks its model (default:
+that engine's default). The result reports the new session's `name` and `engine`, what was carried
+as `carried: { turns, omitted, chars }`, and the reply as `result` when `message` was given. A
+session with no recorded exchange yet cannot be handed off.
+
 **How the conversation travels.** No engine can resume another's session, and each keeps its
 history in its own undocumented on-disk format. So the conversation is replayed as text: a
 `<conversation_history>` block in front of the new session's first message, after which the new
@@ -102,18 +118,18 @@ store.
 recorded per session as it happens. The session's own history buffer is not used for this — it is
 capped by event count, and on a long session the opening request is the first thing it loses. The
 new session inherits the source's working directory and its engine-neutral settings (permission and
-sandbox mode, effort, spend cap, system prompts, extra directories). It does not inherit anything
-written for the source engine — its model, tool allowlists in that engine's tool names, resume ids,
-profiles.
+sandbox mode, effort, spend cap, auto-compact threshold, system prompts, extra directories). It does
+not inherit anything written for the source engine — its model, tool allowlists in that engine's
+tool names, resume ids, profiles.
 
 **What does not.** The source engine's hidden reasoning, which no engine exposes, and the detail of
 tool calls — the new agent sees the replies that described the work, and the workspace itself, which
 the framing tells it to check before relying on anything the history describes.
 
-**When it is too long.** Up to `maxChars` (default 240,000 characters, ~60k tokens) the whole
-conversation is sent. Past that, the opening request is kept, the newest turns fill what is left,
-and one line records how many turns in between were left out: the request says what the work is
-for, the newest turns say where it stands, and the middle is what the workspace can answer.
+**When it is too long.** Up to `maxChars` (default 240,000 characters, ~60k tokens; minimum 4,000)
+the whole conversation is sent. Past that, the opening request is kept, the newest turns fill what
+is left, and one line records how many turns in between were left out: the request says what the
+work is for, the newest turns say where it stands, and the middle is what the workspace can answer.
 
 **A fork, not a move.** The two sessions go their separate ways. The new one starts from the
 source's record, so handing it off again carries the whole conversation rather than only its own
@@ -139,9 +155,11 @@ Code session. Read the outcome by sending a follow-up once the workflow has had
 
 Mid-turn and thread control via the Codex app-server v2 RPCs, surfaced as tools: `codex_interrupt` (cancel the in-flight turn), `codex_steer` (add input without restarting), `codex_fork` (branch the thread), `codex_rollback` (drop the last N turns), `codex_models` (list models + supported reasoning efforts), `codex_thread_list` (list the threads the session can see).
 
+The same engine carries Codex's `/goal`: set and manage it on a session with the `codex_goal_*` tools, or run it as a checked workflow — goal, then verify, then repair on the same thread — with the `goal` node and `clawo goal` ([workflow.md](./workflow.md#goal)).
+
 ### Fan-out (cross-engine parallel)
 
-`fanout_start` runs one task across N engine/model agents in parallel and collects their answers (optional synthesis) — the best-of-N / diverse-perspective primitive. Unlike Council, no rounds/votes/worktrees; use Council for isolated parallel edits. See [tools.md](./tools.md#fan-out-3).
+`fanout_start` runs one task across N engine/model agents in parallel and collects their answers (optional synthesis) — the best-of-N / diverse-perspective primitive. Unlike Council, no rounds/votes/worktrees; use Council for isolated parallel edits. See [tools.md](./tools.md#fanout_start).
 
 Each agent is a session and counts against `maxConcurrentSessions`. Fan-out and Council run no more agents at once than there are free slots when they start, and the rest wait for an agent to finish. When no slot is free at all, the agents fail on the cap rather than wait for sessions they do not own. On a memory-constrained host, the cap is the knob that bounds how many engine processes run at once. An aborted fan-out starts none of the agents still waiting.
 
@@ -149,28 +167,33 @@ Each agent is a session and counts against `maxConcurrentSessions`. Fan-out and
 
 ### Model Switching
 
-Switch models mid-conversation. The session restarts with `--resume` to preserve history:
+Switch models mid-conversation with `switchModel()` (tool: `session_switch_model`). The session restarts on the new model and resumes the engine's own conversation by its resume id, so history is preserved:
 
 ```typescript
 await manager.switchModel('my-task', 'haiku'); // fast model for simple tasks
 await manager.switchModel('my-task', 'opus'); // back to powerful model
 ```
 
+The switch is refused while a turn is running, for a model the registry does not know (a `provider/model` string is accepted), and for a session with no resume id yet — except `agy`, which then restarts fresh. If the restart fails, the session is restarted with its old configuration and the call throws. `setModel()` only changes the stored model, which takes effect at the next restart.
+
 ### Tool Management
 
-Add/remove tool permissions at runtime:
+Add/remove tool permissions at runtime with `updateTools()` (tool: `session_update_tools`), which restarts the session the same way:
 
 ```typescript
 await manager.updateTools('my-task', {
   allowedTools: ['Bash', 'Read'],
-  merge: true, // add to existing list
+  merge: true, // add to the existing lists
 });
 
 await manager.updateTools('my-task', {
-  removeTools: ['Bash'], // revoke Bash access
+  removeTools: ['Bash'], // drop Bash from both lists
+  merge: true, // keep the rest of each list
 });
 ```
 
+Without `merge: true` both lists are replaced, so a list you omit is cleared — including on a call that only passes `removeTools`. The busy and resume-id guards of `switchModel()` apply here too.
+
 ### Context Management
 
 ```typescript
@@ -184,11 +207,18 @@ console.log(`Context: ${status.stats.contextPercent}%`);
 
 `contextPercent` is how full the live context is right now — the current turn's
 prompt over the window the engine actually enforces — so it rises and falls with
-the conversation. `stats.tokensIn` is the different question of how many input
-tokens the session has been billed for in total, which only ever grows.
-`compactSession()` is a no-op on engines whose CLI has no compaction command
-(`codex`, `agy`, `grok`, `opencode`); those sessions log a warning the first
-time it is called.
+the conversation. A persistent `custom` engine is the exception: there it is the
+session's cumulative tokens over the engine config's `contextWindow` (200,000 when
+unset), so it only grows (and a one-shot `custom` engine reports 0).
+`stats.tokensIn` is the different question of how many input tokens the session
+has been billed for in total, which only ever grows.
+
+`compactSession()` runs `/compact` (with the optional summary) on `claude` and a
+persistent `custom` engine, and starts the thread's own compaction on `codex-app`.
+It is a no-op on the one-shot engines whose CLI has no compaction command (`codex`,
+`agy`, `grok`, `opencode`), which log a warning the first time it is called, and a
+silent no-op on `acp` agents, which manage their own context, and on one-shot
+`custom` engines.
 
 A long-lived session can compact itself: start it with `autoCompactPercent`
 (1–99, off by default) and, before each send, the session is compacted first
@@ -215,11 +245,12 @@ against `turns`.
 
 Which outcome counts as a success is the engine's own verdict, not the exit
 code's: `codex` fails a turn that emits `turn.failed` while exiting 0, `agy`
-requires a `SUCCESS` status _and_ a zero exit (it can report success and then die
-in cleanup), `gemini` succeeds on exit 53 because its turn limit resolves,
-`codex-app` requires `status: 'completed'` so a turn cancelled through
-`interrupt()` does not count, and `opencode` refuses a turn on purpose when
-read-only enforcement did not load.
+requires a `SUCCESS` status, a zero exit _and_ a non-empty reply (it can report
+success and then die in cleanup), `codex-app` requires `status: 'completed'` so a
+turn cancelled through `interrupt()` does not count, an `acp` agent must end the
+turn with the stop reason `end_turn`, `opencode` refuses a turn on purpose when
+read-only enforcement did not load, and the legacy `gemini` engine succeeds on
+exit 53 because its turn limit resolves.
 
 **A succeeded turn is not a turn that did the work.** When the engine refuses a
 tool call it usually does not fail the turn. On Claude Code with
@@ -253,41 +284,46 @@ Built-in format translation lets Claude Code CLI talk to non-Anthropic models:
 - **Gemini** thought signature caching (round-trip thinking)
 - Auto-detect provider from model name patterns
 
-See [`src/proxy/`](https://github.com/Enderfga/claw-orchestrator/tree/main/src/proxy) for implementation details.
+A `claude` session started with a non-Claude model and no `baseUrl` starts the proxy on a local port and points the session at it. Configuration is in the proxy section of [Multi-Engine](./multi-engine.md); see [`src/proxy/`](https://github.com/Enderfga/claw-orchestrator/tree/main/src/proxy) for implementation details.
 
 ## Circuit Breaker
 
-SessionManager tracks consecutive failures per engine type. After 3 consecutive start failures for an engine, a circuit breaker opens with exponential backoff (1s × 2^(n-1), capped at 5 minutes). During backoff, new session creation for that engine is rejected with a descriptive error.
+SessionManager tracks consecutive failures per engine type. After 3 consecutive start failures for an engine, a circuit breaker opens with exponential backoff (1s × 2^(n-1) after the n-th consecutive failure, capped at 5 minutes). During backoff, new session creation for that engine is rejected with a descriptive error.
 
 - Resets on successful session start
-- State visible in `health()` response under `circuitBreakers`
+- State visible in the `health()` response (the `sessions_overview` tool) under `circuitBreakers`
 - Constants: `CIRCUIT_BREAKER_THRESHOLD` (3), `CIRCUIT_BREAKER_BACKOFF_BASE_MS` (1s), `CIRCUIT_BREAKER_MAX_BACKOFF_MS` (5 min)
 
 ## Orphaned Process Cleanup
 
-If the plugin crashes without calling `stop()`, child CLI processes (claude, codex, agy, grok, opencode, and legacy engines) may become orphans. SessionManager tracks PIDs in `~/.openclaw/session-pids.json` and cleans up stale processes on startup:
+If the process that owns the sessions exits without stopping them, their engine processes can outlive it. When a session starts, SessionManager records the PID of its engine process in `~/.openclaw/session-pids.json`, together with its own PID, and cleans up on startup:
 
-1. Reads PID file from previous run
-2. For each PID, checks if process is alive (`kill -0`)
-3. Verifies the process command line matches a known CLI binary (prevents killing recycled PIDs)
-4. Sends SIGTERM, then SIGKILL after 3 seconds
-5. Clears the PID file
+1. Reads the PID file left by earlier runs
+2. Skips entries whose owning SessionManager is still alive, and old-format entries that name no owner
+3. For each remaining PID, checks if the process is alive (`kill -0`)
+4. Verifies the process command line names a known engine binary — `claude`, `codex`, `agy`, `grok`, `opencode`, or the legacy `gemini` / `cursor-agent` / `agent` — so a recycled PID is never killed
+5. Sends SIGTERM to the process group and the process, then SIGKILL after 3 seconds
+6. Rewrites the PID file without the stale entries
+
+The one-shot engines have no process running when a session starts, so they have no PID to record. ACP agents and persistent custom engines are recorded, but their binaries are not in the known list, so an orphaned one is left running.
 
 ## Stats & Monitoring
 
-Session stats are returned by `getStats()` and surfaced through `coding_session_status`.
+Session stats are `manager.getStatus(name).stats`, surfaced through `coding_session_status`.
 
 Claude Code–specific stats:
 
-| Field            | Type                                   | Description                                                                                                                               |
-| ---------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `retries`        | number                                 | Total API retries that occurred during the session                                                                                        |
-| `lastRetryError` | string \| undefined                    | Error message from the most recent retry (if any)                                                                                         |
-| `pluginErrors`   | `Array<{plugin, reason}>` \| undefined | Plugins that failed to load due to unmet dependencies, captured from the `system/init` event. `undefined` when no plugin errors occurred. |
+| Field                 | Type                                   | Description                                                                                                                               |
+| --------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `retries`             | number                                 | Total API retries that occurred during the session (present on every engine; only Claude Code reports retries)                            |
+| `lastRetryError`      | string \| undefined                    | Error category of the most recent retry (e.g. `overloaded`, `rate_limit`), or its HTTP status when the CLI gives no category              |
+| `pluginErrors`        | `Array<{plugin, reason}>` \| undefined | Plugins that failed to load due to unmet dependencies, captured from the `system/init` event. `undefined` when no plugin errors occurred. |
+| `refusalFallbacks`    | number \| undefined                    | Turns the model refused and the CLI re-ran on another model (`system/model_refusal_fallback`). `undefined` when none happened             |
+| `lastRefusalFallback` | `{from, to, category?}` \| undefined   | The most recent of those: the refusing model, the model that re-ran the turn, and the refusal category when the CLI reports one           |
 
 ### `system/api_retry` events
 
-When Claude Code CLI performs an API retry (transient errors, overload, etc.) it emits a `system` event with subtype `api_retry`. The plugin parses these events and increments `retries` / updates `lastRetryError` in the session stats. These events are also visible in the session event history returned by `session_grep`.
+When Claude Code CLI performs an API retry (transient errors, overload, etc.) it emits a `system` event with subtype `api_retry`. The plugin parses these events and increments `retries` / updates `lastRetryError` in the session stats. These events are also visible in the session event history returned by `session_grep`, which holds the session's last 100 events.
 
 ```typescript
 const status = manager.getStatus('my-task');
@@ -299,11 +335,14 @@ if (status.stats.lastRetryError) {
 
 ## ISession.pid
 
-All session engine classes expose an optional `pid` readonly property, providing the OS process ID of the underlying CLI subprocess. Returns `undefined` when no process is running.
+All session engine classes expose an optional `pid` readonly property, providing the OS process ID of the underlying CLI subprocess. Returns `undefined` when no process is running — on the one-shot engines, between sends. SessionManager reads it for [orphan cleanup](#orphaned-process-cleanup) and does not expose it; read it from an engine class you construct yourself:
 
 ```typescript
-const session = manager.getSession('my-session');
-console.log(session.pid); // e.g., 12345 or undefined
+import { PersistentClaudeSession } from '@enderfga/claw-orchestrator';
+
+const session = new PersistentClaudeSession({ name: 'probe', cwd: '/path/to/project', permissionMode: 'acceptEdits' });
+await session.start();
+console.log(session.pid); // e.g., 12345
 ```
 
 ## Verifying what a session did
@@ -320,6 +359,3 @@ verify_run({
 
 For work that should be checked as part of running it, use a workflow instead —
 see [`workflow.md`](./workflow.md).
-
-`SendOptions` also accepts `nodeKind` and `taskKind`, both stamped onto the run
-ledger row. `taskKind` is caller-declared and never inferred from the prompt.