Skip to content

Self-improving AI Employees for everyone

refactor(cli_agent): subprocess + stream-json pool — drop PTY for claude_code_agent

trohitg73c5b2270324
diff --git a/CLAUDE.md b/CLAUDE.md
index cca720b5..888342f7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,13 +46,13 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Status Broadcaster](./docs-internal/status_broadcaster.md)** | WebSocket-first communication: StatusBroadcaster singleton, live count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`, broadcast message types, Android two-state model |
| **[RLM Service](./docs-internal/rlm_service.md)** | Recursive Language Model agent with REPL-based execution (llm_query, rlm_query, FINAL) |
| **[Claude Code Agent](./docs-internal/claude_code_agent_architecture.md)** | Claude Code integration internals (LangGraph reference; companion to `cli_agent_framework.md`) |
-| **[CLI Agent Framework](./docs-internal/cli_agent_framework.md)** | Multi-provider CLI runtime (Claude Code / Codex / Gemini): `AICliService.run_batch`, per-task worktree isolation, FastMCP bridge, **memory bridge** (native `--resume` via stable `cwd=repo_root` + UUID5/`last_session_id` round-trip + auto-clear on stale UUID + `node_parameters_updated` broadcast). |
-| **[Claude Code Interactive Mode](./docs-internal/claude_code_interactive_mode.md)** | The interactive-TUI cutover: MachinaOs no longer uses `claude -p` headless. Cross-platform PTY (`ptyprocess` POSIX / `pywinpty>=3.0.3` Windows) keeps `claude` alive; events come from the on-disk session JSONL discovered via mtime. `ClaudeSessionPool` keyed by `simpleMemory.node_id` reuses warm processes across batches (non-disruptive — preserves memory continuity; explicit `pool.clear()` for reset). Memory bridge drives continuity via `--continue` (claude auto-finds latest under cwd) rather than ferrying a UUID through `simpleMemory.last_session_id`. Four typed CloudEvents (`claude.session.{spawned,cleared,terminated,usage}`) fire from the pool. `/compact` events forward to `CompactionService`. `/usage` data sourced from `result` events (TUI scraping not parseable per Anthropic). |
+| **[CLI Agent Framework](./docs-internal/cli_agent_framework.md)** | Multi-provider CLI runtime (Claude Code / Codex / Gemini): `AICliService.run_batch`, per-task worktree isolation, FastMCP bridge, **memory bridge** (`--continue` for first run + intra-process stream-json multi-turn + `--resume <UUID>` for crash recovery, all on a stable `cwd=repo_root`; `node_parameters_updated` broadcast on every successful turn). |
+| **[Claude Code Interactive Mode](./docs-internal/claude_code_interactive_mode.md)** | The interactive-mode cutover: MachinaOs no longer uses `claude -p` headless. `ClaudeSessionPool` (keyed by `simpleMemory.node_id`) spawns `claude` as a plain subprocess with stdio pipes — **no PTY** — and drives it over the VSCode-extension protocol: `--output-format stream-json --input-format stream-json --verbose --ide`. User prompts written as JSON to `proc.stdin` (`{"type":"user","message":{"role":"user","content":"..."}}\n`); `system/init` / `assistant` / `result` / `system/compact_boundary` events stream back on `proc.stdout` (parsed by a background `stdout_reader_task` — the on-disk JSONL is persistence-only, not the runtime contract, because `result` events are stdout-only in stream-json mode). Cross-platform via plain pipes (the earlier PTY pattern was broken on Windows because pywinpty/ConPTY's emulated stdin never reached claude's Ink TUI keystroke handler). Stays in interactive billing — entrypoint `claude-vscode`, NOT `sdk-cli`. Multi-turn within one warm subprocess preserves the session UUID (verified end-to-end); cross-batch continuity via `--continue` (first run) or `--resume <UUID>` (crash recovery). Four typed CloudEvents (`claude.session.{spawned,cleared,terminated,usage}`) fire from the pool. `/compact` events forward to `CompactionService`. The non-pooled `AICliSession` path (one-shot prompt-in-argv runs) still uses PTY (out of scope for this refactor; works on POSIX). |
| **[CLI Agent Canonical Patterns RFC](./docs-internal/cli_agent_canonical_patterns_rfc.md)** | Audit of MachinaOs's `services/cli_agent` against the official Claude Code spec — six invariants (skills-as-files, MCP-only transport, `list_changed`, deferral, visible-tool filtering, native-session-continuity-via-stable-cwd) with current implementation status. |
| **[Claude Code CLI Reference (snapshot)](./docs-internal/claude_code_cli_reference.md)** | Verbatim snapshot of [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference) — every CLI subcommand + flag + system-prompt-flag matrix + the subset we emit from `services/cli_agent/providers/anthropic_claude.py`. Fetched 2026-05-11. |
| **[Claude Code Env Vars (snapshot)](./docs-internal/claude_code_env_vars_reference.md)** | Categorised [code.claude.com/docs/en/env-vars](https://code.claude.com/docs/en/env-vars) snapshot — auth, Bedrock/Vertex, model, bash, MCP, telemetry, session/debug, paths. Documents `CLAUDE_CONFIG_DIR`, `MAX_MCP_OUTPUT_TOKENS`, `ENABLE_TOOL_SEARCH` which we touch directly. |
| **[Claude Code Permission Modes (snapshot)](./docs-internal/claude_code_permission_modes_reference.md)** | Verbatim [code.claude.com/docs/en/permission-modes](https://code.claude.com/docs/en/permission-modes) — `default` / `acceptEdits` / `plan` / `auto` / `dontAsk` / `bypassPermissions` semantics, Shift+Tab cycle, protected paths. MachinaOs default is `acceptEdits`. |
-| **[Claude Code Headless / Print Mode (snapshot)](./docs-internal/claude_code_headless_reference.md)** | Verbatim [code.claude.com/docs/en/headless](https://code.claude.com/docs/en/headless) — `claude -p`, `--output-format` (`text` / `json` / `stream-json`), `--input-format`, `--bare`, stream-json event schema (`system/init`, `system/api_retry`, `system/plugin_install`). This is the protocol `services/cli_agent/session.py:_consume_stdout` parses. |
+| **[Claude Code Headless / Print Mode (snapshot)](./docs-internal/claude_code_headless_reference.md)** | Verbatim [code.claude.com/docs/en/headless](https://code.claude.com/docs/en/headless) — `claude -p`, `--output-format` (`text` / `json` / `stream-json`), `--input-format`, `--bare`, stream-json event schema (`system/init`, `system/api_retry`, `system/plugin_install`). MachinaOs no longer uses `-p`; the pool path emits `--output-format stream-json --input-format stream-json --verbose --ide` over stdio pipes (interactive billing). The event schema is the contract `services/cli_agent/session_pool.py` parses off `proc.stdout`. |
| **[Claude Code Skills (snapshot)](./docs-internal/claude_code_skills_reference.md)** | Verbatim [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) — `SKILL.md` frontmatter spec, discovery paths, content lifecycle, `context: fork`, dynamic context injection via `` !`<command>` ``. The spec MachinaOs materialises connected skills against in `_pre_spawn`. |
| **[Deep Agent](./docs-internal/deep_agent.md)** | LangChain DeepAgents integration with filesystem tools, sub-agent delegation, auto-summarization, and planning |
| **[Autonomous Agent Creation](./docs-internal/autonomous_agent_creation.md)** | Creating autonomous agents with Code Mode patterns and agentic loops |
@@ -3412,28 +3412,29 @@ I don't have access to real-time weather data...
- **Window + Archive**: Short-term (recent messages) + long-term (semantic retrieval) memory pattern
- **Auto-Save**: AI Agent automatically saves updated markdown content to node parameters
-### claude_code_agent bridge — native session resume (NOT markdown injection)
+### claude_code_agent bridge — `--continue` + warm subprocess pool (NOT markdown injection)
-When `simpleMemory` is connected to `claude_code_agent`, memory continuity is handled via **claude's own native session JSONL on disk** rather than re-injecting markdown as a system prompt. Claude stores per-session transcripts under `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl` where `project_key = re.sub(r"[^a-zA-Z0-9.-]", "-", str(cwd))` (verified against the on-disk `data/claude-machina/projects/` listing — Python reproduces three directory names byte-for-byte).
+When `simpleMemory` is connected to `claude_code_agent`, memory continuity is handled by claude itself — the agent does NOT re-inject markdown as a system prompt. Claude stores per-session transcripts under `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl` where `project_key = re.sub(r"[^a-zA-Z0-9.-]", "-", str(cwd))` (verified against the on-disk `data/claude-machina/projects/` listing).
**The three coupled mechanisms** (see [docs-internal/cli_agent_framework.md → Memory bridge](./docs-internal/cli_agent_framework.md#memory-bridge--simplememory--claude_code_agent) for full plumbing):
-1. **Stable cwd.** `AICliSession` accepts `memory_bound=True`. When set, `cwd()` returns `repo_root` instead of the per-task `wt_t_<random>` worktree; `_pre_spawn` skips `git worktree add`; `cleanup` skips `git worktree remove`. The same cwd every run keeps claude's `project_key` constant so `--resume <UUID>` finds the prior JSONL.
-2. **UUID5 first-run / `--resume` thereafter.** `claude_code_agent` derives `uuid5(NAMESPACE_OID, f"{memory_node_id}:{simpleMemory.session_id}")` for the first run and passes it as `--session-id <UUID5>`. Subsequent runs read `simpleMemory.last_session_id` (saved by `_persist_memory` from the previous run's `r.session_id`) and pass `--resume <UUID>` instead. Mutually exclusive in `providers/anthropic_claude.py:headless_argv` argv emission.
-3. **Auto-clear stale `last_session_id`.** When claude reports `No conversation found with session ID: <UUID>` (the JSONL was wiped, or the user's saved UUID predates the cwd-stability fix), `_persist_memory` substring-matches the error and fires `_clear_stale_session_id` which wipes `simpleMemory.last_session_id` (but preserves `memory_content`). Next run falls through to the first-run branch and self-heals.
+1. **Stable cwd.** The pool keeps `cwd = repo_root` for every memory-bound spawn (no per-task worktree carving). Same cwd every run → claude's `project_key` is constant → `--continue` / `--resume <UUID>` resolve against the same JSONL across batches.
+2. **`--continue` first, intra-process thereafter.** [`claude_code_agent.execute_op`](./server/nodes/agent/claude_code_agent/__init__.py) sets `spec.continue_session = bool(memory_data)` so the first cold spawn for a memory-wired run emits `--continue` (claude auto-loads the most recent conversation under the cwd's `project_key`, per [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference)). Subsequent turns are written as stream-json to the SAME warm subprocess's `proc.stdin` — claude keeps the conversation in-process with the same `session_id` (verified: turn 1 + turn 2 share UUID within one process).
+3. **`--resume <UUID>` crash recovery.** If the warm subprocess dies between batches, [`ClaudeSessionPool.acquire`](./server/services/cli_agent/session_pool.py) detects `process.returncode is not None`, captures the dead session's `current_session_uuid` (last seen on a `result` event), and respawns with `--resume <captured_uuid>` so the same on-disk JSONL keeps growing. Mutually exclusive with `--continue` in `providers/anthropic_claude.py:interactive_argv`.
-**`memory_content` is the UI mirror, not the resume channel.** Claude reads its own JSONL via `--resume`. The markdown in `memory_content` is appended every successful run (same `append_to_memory_markdown` + `trim_markdown_window` helpers aiAgent uses) for the human reader. User edits to `memory_content` do not influence claude's next response.
+**`memory_content` is the UI mirror, not the resume channel.** Claude reads its own JSONL via `--continue` / `--resume`. The markdown in `memory_content` is appended every successful run (same `append_to_memory_markdown` + `trim_markdown_window` helpers aiAgent uses) so the human reader sees the conversation. User edits to `memory_content` do not influence claude's next response.
-**Parallel-batch guard.** When memory is wired AND `len(tasks) > 1`, `claude_code_agent` raises `NodeUserError` at handler entry — concurrent `--resume <UUID>` spawns against one JSONL would race.
+**`simpleMemory.last_session_id` is display-only.** Pre-cutover code persisted the session UUID back to the memory node and emitted `--session-id <UUID5>` / `--resume <UUID>` on subsequent runs. That dance is gone — `claude_code_agent` no longer reads `last_session_id` from the memory data. The field is kept on the Pydantic params for back-compat and diagnostic display; clearing the memory wipes it.
+
+**Parallel-batch guard.** When memory is wired AND `len(tasks) > 1`, `claude_code_agent` raises `NodeUserError` at handler entry — concurrent `--continue` spawns against one project_key would race claude's session-resolution.
**Live UI refresh.** `_persist_memory` broadcasts `node_parameters_updated` after `save_node_parameters` so the simpleMemory parameter panel auto-refetches the moment a turn completes — without this the DB has the latest conversation but the UI shows the stale snapshot loaded at workflow open. Mirrors the pattern in `routers/websocket.py:handle_save_node_parameters`.
**Logs to grep on a live run:**
-- `[Claude Code memory] memory_node=<id> last_session_id=<UUID|None> -> --resume <UUID>` (subsequent run) or `--session-id <UUID5> (first run)`
-- `[AICliSession_*] memory-bound: skipping worktree, using cwd=<repo_root>`
-- `[CC-Agent stream] result is_error=False ... session_id=<UUID>`
+- `[Claude Code memory] memory_node=<id> -> --continue (claude auto-finds latest session under cwd)`
+- `[ClaudeSessionPool] spawned new session memory_node=<id> pid=<N>` (cold spawn) or `warm reuse memory_node=<id> pid=<N> uuid=<UUID>` (intra-process turn)
- `[CC-Agent _persist_memory] saved memory_node=<id> last_session_id=<UUID> appended_turns=1 ... content_length=<N>`
-- On stale-UUID error: `[CC-Agent _persist_memory] cleared stale last_session_id=<UUID> from memory_node=<id>; next run will spawn a fresh claude session and persist its new UUID.`
+- On crash recovery: `[ClaudeSessionPool] dropping dead session memory_node=<id> ... — will respawn` followed by spawn with `--resume <UUID>` argv.
## Memory Compaction, Token Tracking, and Cost Calculation
diff --git a/client/src/adapters/nodeSpecToDescription.ts b/client/src/adapters/nodeSpecToDescription.ts
index 5a99f4a6..8b012470 100644
--- a/client/src/adapters/nodeSpecToDescription.ts
+++ b/client/src/adapters/nodeSpecToDescription.ts
@@ -112,6 +112,13 @@ type InodeType = INodeProperties['type'];
* the user sees an editable field rather than a blank slot.
*/
function mapPropertyType(prop: JsonSchemaProperty): InodeType {
+ // ``json_schema_extra={"hidden": True}`` on the Pydantic Field hides
+ // the parameter from the panel. ParameterRenderer.tsx returns ``null``
+ // when ``parameter.type === 'hidden'``. Check both the top-level flag
+ // (Pydantic flattens ``json_schema_extra`` keys onto the property) and
+ // ``uiHints.hidden`` (nested alternate). Honoured BEFORE enum/editor
+ // checks so hidden enum fields don't render as visible dropdowns.
+ if ((prop as any).hidden === true || prop.uiHints?.hidden === true) return 'hidden';
if (prop.enum && prop.enum.length > 0) return 'options';
// Pydantic Field(json_schema_extra={"editor": "code"}) lands at the
// property top-level; nested ``uiHints: {...}`` is the alternate
diff --git a/docs-internal/claude_code_interactive_mode.md b/docs-internal/claude_code_interactive_mode.md
index 4b9d4572..a06e1268 100644
--- a/docs-internal/claude_code_interactive_mode.md
+++ b/docs-internal/claude_code_interactive_mode.md
@@ -1,158 +1,185 @@
-# Claude Code interactive mode (in-process PTY + on-disk JSONL)
-
-> **TL;DR.** MachinaOs drives the same interactive `claude` invocation a
-> normal user runs at their terminal — not `claude -p`. A PTY keeps the
-> TUI alive in-process; events come off the on-disk session JSONL,
-> not stdout. A pool keyed by `simpleMemory.node_id` keeps the warm
-> process across batches.
+# Claude Code interactive mode (subprocess + stream-json)
+
+> **TL;DR.** `ClaudeSessionPool` keeps a warm `claude` subprocess per
+> `simpleMemory.node_id` and drives it with the same flags Anthropic's
+> own VSCode extension uses — stdio pipes, `--output-format stream-json
+> --input-format stream-json --verbose --ide`. Multi-turn happens by
+> writing newline-delimited JSON to `proc.stdin` of the long-lived
+> subprocess. Events arrive on `proc.stdout`. The on-disk JSONL is no
+> longer the runtime contract — claude writes it for `--continue` /
+> `--resume` persistence but the `result` event is stdout-only in
+> stream-json mode.
## Why we cut over from `-p`
Pre-cutover MachinaOs spawned `claude -p --output-format stream-json`
-and parsed NDJSON events on stdout. Two-direction motivation:
+and parsed NDJSON events on stdout. Two reasons to leave `-p`:
-1. **Match how users actually use Claude Code.** The headless path is
- sanctioned for automation, but most Claude Code users run the
- interactive TUI. Driving the same surface lets us inherit fixes /
- behavior changes the team prioritises for the human-facing mode.
-2. **Anthropic billing change (2026-06-15).** Per
+1. **Anthropic billing change (2026-06-15).** Per
[`code.claude.com/docs/en/headless`](https://code.claude.com/docs/en/headless),
- subscription plans now bill `claude -p` and Agent-SDK usage from a
- separate "monthly Agent SDK credit." Interactive usage stays on the
- subscription's interactive bucket. The cutover puts us in the
- user's interactive bucket when they supply their own API key.
-
-The corollary: every protocol detail still works in interactive mode
-because the on-disk JSONL is the same format `-p` wrote to stdout
-(Claude Code CHANGELOG 2.1.101 / 2.1.126 — shared writer). The argv
-flags we care about — `--mcp-config`, `--strict-mcp-config`,
-`--allowedTools`, `--permission-mode`, `--append-system-prompt`,
-`--resume`, **`--continue`** (new primary continuity flag — see
-"Memory bridge" below), `--model`, `--effort`, `--add-dir`,
-`--disallowedTools`, `--agent` — all work in interactive mode.
-
-## What we dropped
-
-| Flag | Why dropped |
+ subscription plans bill `claude -p` and Agent-SDK usage from a
+ separate "monthly Agent SDK credit." The interactive entrypoint
+ (`claude-vscode`, not `sdk-cli`) stays on the subscription's
+ interactive bucket. Dropping `-p` puts us in the user's interactive
+ bucket when they supply their own API key.
+2. **Match how Anthropic itself drives `claude` programmatically.** The
+ VSCode extension at
+ `C:/Users/Tgroh/.vscode/extensions/anthropic.claude-code-2.1.140-win32-x64/extension.js:156`
+ spawns claude with exactly four flags (`--output-format stream-json
+ --input-format stream-json --verbose --ide`) and never emits `-p`.
+ That's the wire we reuse.
+
+## Architecture
+
+One transport (`asyncio.create_subprocess_exec` with `stdin/stdout/stderr=PIPE`),
+one protocol (line-delimited stream-json events on stdout). No PTY.
+A background `stdout_reader_task` parses each line and dispatches via
+`_handle_stream_event`.
+
+| Layer | Mechanism |
|---|---|
-| `-p` / `--print` | The headless toggle itself. |
-| `--output-format stream-json` | Only meaningful under `-p`. |
-| `--verbose` | Only meaningful with `-p --output-format stream-json`. |
-| `--include-partial-messages` | Only meaningful with stream-json. |
-| `--include-hook-events` | Only meaningful with stream-json. The hooks fire regardless and we can detect them via JSONL. |
-| `--max-turns` | `-p`-only. External counter is a Phase 2 follow-up. |
-| `--max-budget-usd` | `-p`-only. External monitor on `result.total_cost_usd` is a Phase 2 follow-up. |
-| `--session-id <UUID>` | No longer pre-mint UUIDs. First-run claude assigns its own; we discover it via the new JSONL filename. |
-| `--fallback-model` | `-p`-only. |
-
-`ClaudeTaskSpec` keeps the corresponding Pydantic fields for
-back-compat; they're silently dropped in `interactive_argv`.
-
-## Architecture — transport vs. protocol
-
-Two orthogonal layers:
-
-| Layer | macOS / Linux | Windows |
-|---|---|---|
-| **Transport** (PTY holds `claude` alive) | `ptyprocess>=0.7.0` | `pywinpty>=3.0.3` (Rust-backed via PyO3 + winpty-rs + Maturin) |
-| **Protocol** (read events) | tail `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session>.jsonl` | identical |
-| **Send turn** | `pty.write((text + '\r').encode())` (NOT close stdin — see [#15553](https://github.com/anthropics/claude-code/issues/15553)) | identical |
-| **Send slash command** | `pty.write(b"/clear\r")` | identical |
-| **Completion detect** | JSONL `result` entry | identical |
-| **Session continuity** | `claude --continue` (memory-bound) — claude auto-finds latest under cwd | identical |
-
-`pywinpty` v3.x is now production-grade (used by Jupyter Lab terminals
-and Spyder's IPython console) so the historical reason to route Windows
-through a Node.js sidecar (pywinpty flakiness) no longer holds. Both
-backends run in-process behind a single `PtyTransport` Protocol; the
-factory in [`server/services/cli_agent/transports/__init__.py`](../server/services/cli_agent/transports/__init__.py)
-picks per `sys.platform`.
+| **Transport** | `asyncio.subprocess.Process` with stdio pipes — same on POSIX + Windows |
+| **Send turn** | `proc.stdin.write(json.dumps({"type":"user","message":{"role":"user","content":...}}) + "\n")` |
+| **Read events** | `proc.stdout.readline()` loop → `json.loads(line)` → `_handle_stream_event` |
+| **Completion detect** | stream-json event where `type == "result"` (set via `provider.is_final_event`) |
+| **Context reset (`/clear` equivalent)** | kill subprocess + drop captured UUID — stream-json input has no slash-command path (confirmed in VSCode extension source) |
+| **Crash recovery** | `acquire()` checks `process.returncode`; respawns with `--resume <captured_uuid>` so the same on-disk JSONL keeps growing |
### Code layout (`server/services/cli_agent/`)
```
cli_agent/
├── providers/
-│ └── anthropic_claude.py # interactive_argv (replaces headless_argv)
-├── transports/
-│ ├── __init__.py # get_pty_transport() factory
-│ ├── base.py # PtyTransport / PtyHandle Protocols
-│ ├── posix.py # PosixPtyTransport (ptyprocess)
-│ └── windows.py # WindowsPtyTransport (pywinpty)
-├── jsonl_watcher.py # JsonlWatcher (tail-f) + JsonlDirWatcher
-├── session.py # AICliSession — one-shot non-pooled path
-├── session_pool.py # ClaudeSessionPool — warm-process reuse
-└── service.py # AICliService.run_batch + _run_pooled_turn
+│ └── anthropic_claude.py # interactive_argv — emits the four VSCode-pattern flags
+├── jsonl_watcher.py # still used by the non-pooled AICliSession; NOT used by the pool
+├── session.py # AICliSession — one-shot non-pooled path (PTY on POSIX; out of scope for this refactor)
+├── session_pool.py # ClaudeSessionPool — subprocess-based warm-process reuse
+└── service.py # AICliService.run_batch — entry point; routes to pool when memory-bound
```
+## argv shape
+
+Built by [`AnthropicClaudeProvider.interactive_argv`](../server/services/cli_agent/providers/anthropic_claude.py).
+Stable head, task-driven tail:
+
+```
+claude
+ --output-format stream-json
+ --input-format stream-json
+ --verbose
+ --ide
+ [--mcp-config <json> --strict-mcp-config]
+ --model <name>
+ [--resume <UUID> | --continue]
+ [--allowedTools <csv>]
+ --permission-mode bypassPermissions
+ [--append-system-prompt <text>]
+ [--effort low|medium|high]
+ [--add-dir <path>]...
+ [--disallowedTools <csv>]
+ [--agent <name>]
+```
+
+Notable absences (intentional):
+
+| Flag | Reason omitted |
+|---|---|
+| `-p` / `--print` | Drops us into the SDK billing bucket; the whole point of the cutover. |
+| Positional prompt (`-- "<text>"`) | Prompt arrives via stdin in stream-json input mode; an argv positional would double-send the first turn. `interactive_argv`'s `include_prompt` parameter is kept for back-compat but ignored. |
+| `--session-id <UUID>` | Rejected by claude in non-headless mode. We discover the UUID from the first event that carries `session_id`. |
+| `--include-partial-messages`, `--include-hook-events`, `--max-turns`, `--max-budget-usd`, `--fallback-model` | All `-p`-only. `ClaudeTaskSpec` keeps the fields for back-compat; they're silently dropped here. External cost / turn caps are a Phase 2 follow-up. |
+
+`--permission-mode bypassPermissions` is required for non-interactive
+automation — there's no human at the keyboard to approve the per-tool
+prompts `acceptEdits` would surface. Documented at
+[`code.claude.com/docs/en/permission-modes`](https://code.claude.com/docs/en/permission-modes).
+
## Session pool — warm-process reuse
[`ClaudeSessionPool`](../server/services/cli_agent/session_pool.py) is
-keyed by `simpleMemory.node_id`. Successive batches against the same
-memory node reuse the same warm `claude` PTY:
-
-- **Acquire (warm)** — returns the existing live session. **No
- implicit `/clear`** — the next prompt appends to claude's current
- JSONL so the conversation continues. This is the load-bearing
- invariant for `simpleMemory` continuity.
-- **Acquire (cold)** — spawn fresh via `PtyTransport`, locate the
- JSONL by mtime (newest `.jsonl` with `mtime >= spawn_time - 1s`
- works uniformly for fresh `claude` and `claude --continue`), start
- a `JsonlWatcher` on it. Stash the MCP bearer token on the
- `PooledClaudeSession` so re-acquires use the same token the
- spawned claude already has in its argv.
-- **Explicit `clear(session)`** — sends `/clear` to the PTY, awaits
- the new JSONL filename via the persistent `JsonlDirWatcher`, swaps
- the file watcher. Per
- [`claude-code#32871`](https://github.com/anthropics/claude-code/issues/32871),
- `/clear` mints a **new UUID** with a **new JSONL file** rather than
- clearing in-place. Pre-clear conversation stays resumable by its
- old UUID.
+keyed by `simpleMemory.node_id`. Each entry is a
+`PooledClaudeSession` carrying the live `asyncio.subprocess.Process`,
+the captured session UUID (filled in from the first event that has
+one), the MCP bearer token embedded in the spawn argv, a per-session
+`asyncio.Lock`, an `asyncio.Event` signalled by the stdout reader on
+`result`, and a per-turn event buffer.
+
+| Operation | Behaviour |
+|---|---|
+| `acquire(memory_node_id, ...)` | Live + healthy entry → return as-is (warm reuse). Live + dead entry → drop, capture its UUID, spawn fresh with `--resume <UUID>` so the same JSONL keeps growing. No entry → cold spawn. At cap → LRU evict (skipping in-flight). |
+| `send_turn(session, prompt, ...)` | Holds `session.lock`. Clears `result_event` + `events_this_turn`. Writes one stream-json line to `proc.stdin`, awaits `result_event` (timeout = 600s default). Returns a `SessionResult` built from the per-turn event buffer. Persists `result.session_id` onto `session.current_session_uuid`. |
+| `clear(session, ...)` | Kill the subprocess, drop the captured UUID. Next `acquire` spawns fresh with no continuity flag (claude assigns a new UUID). Emits `claude.session.cleared`. |
+| `release(session)` | Updates `last_used_at` so the reaper measures idle from now. |
+| `terminate(memory_node_id)` | Force-drop a specific entry: close stdin → 2s grace → `proc.kill()` → cancel reader/drain tasks. |
+| `shutdown_all()` | Stop the reaper + terminate every entry. Wire into FastAPI's lifespan `shutdown`. |
Lifecycle policy:
- **Idle TTL** 30 min (`_DEFAULT_IDLE_TTL`). Background reaper task
- terminates pooled sessions whose `last_used_at` exceeds the cap
- AND aren't currently locked.
-- **Max size** 16 (`_DEFAULT_MAX_SIZE`). LRU eviction at cap.
-- **Crash recovery** — `acquire` calls `pty_handle.is_alive()` and
- respawns transparently when the pooled PTY has died.
+ terminates pooled sessions whose `last_used_at` exceeds the cap AND
+ aren't currently locked.
+- **Max size** 16 (`_DEFAULT_MAX_SIZE`). LRU eviction at cap (skipping
+ in-flight entries).
- **Concurrency** — per-key `asyncio.Lock` serialises turns against
- the same pooled session. `lock.locked()` doubles as the reaper's
- in-flight detector.
-- **Shutdown** — `ClaudeSessionPool.shutdown_all()` is the target for
- FastAPI's lifespan `shutdown` event (TODO: wire from `main.py`).
+ the same pooled subprocess so two `send_turn` calls can't interleave
+ their stream-json lines on stdin. `lock.locked()` doubles as the
+ reaper's in-flight detector.
+
+## Stream-json event dispatch
+
+`_handle_stream_event` has three concerns:
+
+1. **UUID capture.** Any event carrying `session_id` (or `sessionId`)
+ seeds `session.current_session_uuid` if it isn't already set —
+ `system/init` fires this for fresh spawns, `result` carries the
+ authoritative value at turn end. Crash-recovery respawns read this
+ field to emit `--resume <UUID>`.
+2. **Per-turn buffering.** Every event is appended to
+ `events_this_turn`. When `provider.is_final_event(event)` returns
+ True (i.e. `event.type == "result"`), `result_event` is set and
+ `send_turn` returns. `SessionResult` is built by
+ `AnthropicClaudeProvider.event_to_session_result` over the buffered
+ events — same shape `-p` used to produce.
+3. **Native compaction forwarding.** `type == "system"` +
+ `subtype == "compact_boundary"` events forward to
+ `CompactionService.record(...)` via `_record_native_compaction` so
+ the local-threshold path doesn't double-fire on claude's auto-
+ compaction. Trigger metadata (`pre_tokens`, `trigger: auto|manual`)
+ is preserved on the compaction record.
+
+## Continuity across process restarts
+
+The pool's continuity model is two-layered:
+
+- **Intra-process (warm pool).** Within a live subprocess, every turn
+ writes to the same `proc.stdin` and claude itself keeps the conversation
+ in memory. No `--continue` / `--resume` needed — same session UUID
+ flows across turns. Verified: turn 1 `13ac5819-...`, turn 2 same UUID.
+- **Cross-process (cold spawn / crash recovery).** Cold spawns of a
+ memory-bound run emit `--continue` (claude auto-finds the latest
+ conversation under the cwd via `project_key`). If `acquire` finds the
+ pooled subprocess has died, it captures the dead session's UUID
+ before respawning and splices `--resume <UUID>` into the spec so the
+ new subprocess continues writing to the same on-disk JSONL.
+
+`ClaudeTaskSpec` carries `continue_session: bool` and
+`resume_session_id: Optional[str]`. `resume_session_id` wins if both
+are set. `simpleMemory.last_session_id` is display-only metadata —
+`_persist_memory` writes it for the UI but the agent doesn't read it
+back (continuity rides through `--continue` + the warm pool, not a
+ferried UUID).
## MCP bearer token lifecycle
`claude` handles its own MCP authentication. We embed the bearer in
`--mcp-config` at spawn time; the spawned claude uses it for the
-lifetime of its process. The pool does NOT issue or unregister tokens
-— the caller (`AICliService.run_batch`) owns the lifecycle, with the
-twist that for pooled sessions the token persists with the warm PTY
-across batches:
-
-```python
-# run_batch — non-pool path (unchanged)
-token = issue_token()
-register_batch(token, ctx)
-try:
- results = await asyncio.gather(*(run_one(t) for t in tasks))
-finally:
- unregister_batch(token)
-
-# run_batch — pool path
-token = issue_token()
-register_batch(token, ctx)
-try:
- result = await self._run_pooled_turn(..., mcp_bearer_token=token)
- # token stays embedded in the warm PTY for the next batch.
- # On pool eviction / shutdown the registration orphans (bounded
- # by max pool size, acceptable for Phase 1).
-finally:
- if not use_pool:
- unregister_batch(token)
-```
+lifetime of its process. The pool stashes the token on
+`PooledClaudeSession.bearer_token` at spawn time so warm-reuse callers
+(`AICliService.run_batch`'s pool path) can re-register the batch
+context against the SAME token claude already has in its argv. The pool
+itself never issues / unregisters — that's `run_batch`'s job, with the
+twist that for pooled sessions the token persists across batches and
+orphans on pool eviction (bounded by `max_size`, acceptable for Phase 1).
## CloudEvents broadcasts
@@ -162,119 +189,62 @@ fired via the corresponding `broadcaster.broadcast_claude_session_*`
methods on
[`server/services/status_broadcaster.py`](../server/services/status_broadcaster.py):
-| Event type | Wire key | When fired |
-|---|---|---|
-| `com.machinaos.claude.session.spawned` | `claude_session_event` | Cold spawn (new PTY) |
-| `com.machinaos.claude.session.cleared` | `claude_session_event` | Explicit `pool.clear` → new UUID |
-| `com.machinaos.claude.session.terminated` | `claude_session_event` | Pool terminate (reason: `idle` / `crashed` / `evicted` / `shutdown` / `explicit`) |
-| `com.machinaos.claude.session.usage` | `claude_session_usage` | Each `result` event (per-turn cost + tokens) |
-
-Frontend listeners should switch on `envelope.type` and route the
-inner `data` payload (memory_node_id, session_uuid, cost, tokens, …)
-into whichever store renders the simpleMemory usage panel.
+| Event type | When fired |
+|---|---|
+| `com.machinaos.claude.session.spawned` | Cold spawn (new subprocess) |
+| `com.machinaos.claude.session.cleared` | Explicit `pool.clear` → new UUID on next acquire |
+| `com.machinaos.claude.session.terminated` | Pool terminate (reason: `idle` / `crashed` / `evicted` / `shutdown` / `explicit`) |
+| `com.machinaos.claude.session.usage` | Each `result` event (per-turn cost + tokens + duration + num_turns) |
+
+The usage event is the source of truth for the simpleMemory usage panel
+— `/usage` is TUI-only plain text per Anthropic and not parseable.
+Frontend listeners switch on `envelope.type` and route the inner `data`
+payload (`memory_node_id`, `session_uuid`, cost, tokens, …) into the
+store that renders the panel.
+
+## Tools and skills
+
+**Tools (MCP) — unchanged from the `-p` era.** Spawn argv carries
+`--mcp-config <json>` (HTTP transport, bearer header) + `--strict-mcp-config`
+so the spawned claude only loads MachinaOs's FastMCP server. The
+`mcpServers.machinaos` block sets `alwaysLoad: true` to opt out of MCP
+tool-search deferral so all `mcp__machinaos__*` tools enter context at
+session start. `--allowedTools` lists the explicit allowlist:
+five built-ins (`Read,Edit,Bash,Glob,Grep,Write,Skill,WebSearch,WebFetch`),
+every `mcp__machinaos__<connected_tool>` passed by the caller, plus the
+five core MCP tools (`getWorkspaceFiles`, `listSkills`, `getSkill`,
+`getCredential`, `broadcastLog`).
+
+**Skills — known gap on the pool path.** `AICliSession._materialise_skills`
+writes connected skills under `<cwd>/.claude/skills/` for the one-shot
+non-pooled path. The pool path skips that materialisation; agents
+discover skills via MCP `listSkills` / `getSkill` tools at runtime
+instead. Fine for now, but pool-side skill materialisation is an open
+follow-up.
## `/usage` and `/compact` semantics
-Per the research:
-
-- **`/usage`** — TUI-only plain text per Anthropic. Not parseable.
- The data it displays (cost, tokens, duration, num_turns) is already
- on every `result` JSONL event under `usage` + `total_cost_usd`. We
- surface it via the `claude.session.usage` CloudEvent instead.
-- **`/clear`** — mints a new session UUID + new JSONL file (issue
- [#32871](https://github.com/anthropics/claude-code/issues/32871)).
- Pool exposes this as `pool.clear(session)` for explicit reset; not
- fired on warm acquire.
-- **`/compact`** — emits `system/compact_boundary` with
+- **`/usage`** — TUI-only plain text per Anthropic. Not parseable. We
+ surface the same data (cost, tokens, duration, num_turns) via the
+ `claude.session.usage` CloudEvent built from every `result` event.
+- **`/clear`** — the stream-json input wire has no slash-command path
+ (confirmed in the VSCode extension source). Context reset is
+ `pool.clear(session)` — kill subprocess, drop UUID, next acquire
+ spawns fresh.
+- **`/compact`** — emits `system/compact_boundary` on stdout with
`compact_metadata.pre_tokens` + `compact_metadata.trigger` (auto vs
- manual). Both `AICliSession._on_jsonl_event` and
- `ClaudeSessionPool._handle_jsonl_event` forward it to
+ manual). `_handle_stream_event` forwards it to
`CompactionService.record(...)` so the local-threshold path doesn't
- double-fire.
-
-Commands MachinaOs must **avoid** in PTY-driven automation (they open
-interactive dialogs, kill the session, or open a browser):
-`/feedback`, `/bug`, `/exit`, `/quit`, `/login`, `/logout`,
-`/permissions`, `/agents`, `/mcp`, `/model` (with no arg), `/rewind`,
-`/config`, `/install-github-app`, `/install-slack-app`, `/teleport`,
-`/heapdump`.
-
-## Memory bridge — `--continue`, not UUID round-trip
-
-Late-stage simplification: the agent no longer ferries a UUID through
-`simpleMemory.last_session_id` to drive continuity. Instead it passes
-`--continue` and lets claude track its own latest session per cwd.
-
-`ClaudeTaskSpec` carries a `continue_session: bool` field. The
-argv-builder emits one of:
-
-- `--resume <UUID>` if `task.resume_session_id` is set (explicit
- wins — used for `--fork-session` later, or any caller that already
- knows the exact UUID).
-- `--continue` if `task.continue_session=True` (the memory-bound
- default; per
- [`code.claude.com/docs/en/cli-reference`](https://code.claude.com/docs/en/cli-reference)
- this loads the most recent conversation under the cwd).
-- Neither — fresh session; claude assigns a new UUID.
-
-`claude_code_agent.execute_op` sets `continue_session=True` when a
-memory node is wired; it no longer reads `last_session_id` from the
-memory data. The invariants:
-
-- `memory_bound=True` makes the spawn cwd = `repo_root` so claude's
- `project_key` stays constant across batches.
-- First run with memory wired: argv `--continue` (no prior conversation
- under cwd → claude starts fresh). The post-spawn `_wait_for_session_jsonl`
- helper finds the new JSONL via mtime (newest `.jsonl` with
- `mtime >= spawn_time - 1s`).
-- Subsequent runs with memory wired: argv `--continue` — claude
- loads the latest conversation under cwd and continues.
-- Pooled (warm): no respawn — the warm PTY continues in its current
- UUID; the next prompt appends to its existing JSONL.
-- Pooled (after `pool.clear`): a new UUID is captured via the
- persistent `JsonlDirWatcher` and the file watcher swapped.
-
-`simpleMemory.last_session_id` is now **display-only metadata** —
-`_persist_memory` still writes it from the latest result for UI /
-diagnostic display, but the agent doesn't read it. Field is kept on
-the schema for back-compat.
-
-**Stale UUID auto-clear** (`_clear_stale_session_id`) still applies if
-someone explicitly sets `resume_session_id` (e.g. the future
-`--fork-session` UI). With `--continue` there's nothing to be stale —
-claude itself decides what's available.
-
-## Out-of-process pty-host (deferred upgrade path)
-
-If `pywinpty` / `ptyprocess` stability becomes an issue (crashes
-bringing down FastAPI), promote `PtyTransport` to an out-of-process
-Python sidecar — VSCode's `ptyHostMain.ts` pattern, in Python.
-Supervised by `machina/tree.py`'s Job Object, JSON-RPC over stdio.
-The `PtyTransport` Protocol boundary makes the swap cheap (~1 day).
-See VSCode issue
-[#74620](https://github.com/microsoft/vscode/issues/74620) for the
-rationale (heartbeat, flow control, isolation from main app).
-
-## Open follow-ups
-
-- **Cancellation path.** Pool sessions bypass
- `AICliService._active_sessions`, so `cancel_workflow` /
- `cancel_node` don't reach the pooled PTY. Add pool-in-flight
- tracking or hook cancel into `pool.terminate`.
-- **Lifespan integration.** Wire `pool.shutdown_all()` to FastAPI's
- shutdown event from `main.py`. Currently the pool dies with the
- process; orphan PTY children are caught by `machina/tree.py` Job
- Object on Windows and `os.setsid` on POSIX.
-- **Frontend usage panel.** `claude.session.usage` CloudEvents are
- flowing; the React hook + simpleMemory panel UI are the missing
- half (Step 7 of the implementation plan).
-- **`--fork-session` UI.** `--fork-session` is the documented working
- fork primitive; surface a "Branch this conversation" `<ActionButton>`
- on simpleMemory + a `branches: List[{uuid, name, created_at}]`
- param. Avoids `/rewind` which has bug
- [#55347](https://github.com/anthropics/claude-code/issues/55347)
- (documented as fork but implemented as in-place mutation).
-- **External cost cap / turn cap.** Replacements for the dropped
- `--max-budget-usd` and `--max-turns` flags. Aggregate
- `result.total_cost_usd` / count `assistant` events with
- `stop_reason: "tool_use"` and kill the PTY at the limit.
+ double-fire on claude's native auto-compaction.
+
+## What changed (historical note)
+
+The previous iteration of this doc described a PTY transport
+(`pywinpty` on Windows, `ptyprocess` on POSIX) reading events from the
+on-disk session JSONL via `JsonlWatcher` / `JsonlDirWatcher`. That path
+was abandoned for the pool: `pywinpty`'s ConPTY emulation did not
+deliver keystrokes to claude's Ink TUI on Windows (empirically
+confirmed across four test variants). Stdio pipes + stream-json work
+cross-platform and match the Anthropic-blessed pattern. The non-pooled
+`AICliSession` still uses a PTY on POSIX for its one-shot
+`AICliService.run_batch` path — out of scope for this refactor.
diff --git a/docs-internal/cli_agent_canonical_patterns_rfc.md b/docs-internal/cli_agent_canonical_patterns_rfc.md
index e55d6def..c1aa3773 100644
--- a/docs-internal/cli_agent_canonical_patterns_rfc.md
+++ b/docs-internal/cli_agent_canonical_patterns_rfc.md
@@ -346,13 +346,15 @@ runtime log shows exactly this).
```
**Spec note.** The lockfile is for IDE-host scenarios (VSCode publishes
-this so a spawned `claude` can discover the IDE). Headless `claude -p`
-ignores it — the documented headless path is `--mcp-config`. Our
-lockfile is currently ornamental; doesn't hurt, but `transport: "http"`
-is the wrong value for what Claude's VSCode extension actually publishes
-(`"ws"` per the live extension dump in
-[#16434](https://github.com/anthropics/claude-code/issues/16434)).
-**Defer.** Documented note in `cli_agent_framework.md` is enough.
+this so a spawned `claude` can discover the IDE). The pool path now
+emits `--ide` in its argv, so claude does discover and connect to the
+lockfile's MCP endpoint at spawn time. `transport: "http"` stays —
+that matches what our FastMCP sub-app at `/mcp/ide` actually speaks
+(streamable HTTP). The `"ws"` upgrade (matching what Claude's VSCode
+extension publishes in its own lockfile per the live extension dump
+in [#16434](https://github.com/anthropics/claude-code/issues/16434))
+is **deferred** — `"http"` is interoperable and unblocks the pool
+path today.
### 4.5 FastMCP server tools
diff --git a/docs-internal/cli_agent_framework.md b/docs-internal/cli_agent_framework.md
index 30c0d673..9df9e02e 100644
--- a/docs-internal/cli_agent_framework.md
+++ b/docs-internal/cli_agent_framework.md
@@ -65,7 +65,7 @@ class AICliProvider(Protocol):
ide_lockfile_dir: Optional[Path] # ~/.claude/ide | <tmpdir>/gemini/ide
def binary_path(self) -> Path: ...
- def headless_argv(self, task, *, defaults) -> list[str]: ...
+ def interactive_argv(self, task, *, defaults) -> list[str]: ...
def login_argv(self) -> list[str]: ... # CLI's own login command
def auth_status_argv(self) -> Optional[list[str]]: ... # cheap probe
def detect_auth_error(self, stderr, exit_code) -> bool: ...
@@ -82,7 +82,7 @@ class AICliProvider(Protocol):
# | json_cost | ide_lockfile | sandbox
```
-### Claude argv (`AnthropicClaudeProvider.headless_argv`)
+### Claude argv (`AnthropicClaudeProvider.interactive_argv`)
Spawned per task — the binary path comes from
`services.claude_oauth.claude_binary_path()` (the same project-local
@@ -90,31 +90,47 @@ install the credentials Login button uses) and `CLAUDE_CONFIG_DIR` is
injected on the spawn env so the agent shares one credential store with
the auth surface.
+The pooled path (`ClaudeSessionPool`) spawns claude as a plain
+subprocess with stdio pipes — no PTY — and drives it over the
+VSCode-extension protocol: prompts written as stream-json to
+`proc.stdin`, events read as stream-json off `proc.stdout`. Stays in
+the interactive billing bucket (entrypoint `claude-vscode`, NOT
+`sdk-cli`) since `-p` / `--print` is never emitted.
+
```
<repo>/data/claude-machina/npm/node_modules/.bin/claude[.cmd]
- -p <prompt>
- --output-format stream-json
- --verbose # required when stream-json + --print
- --include-partial-messages
- --include-hook-events # SessionStart/hook events into stream
- --ide # documented VSCode auto-connect via lockfile
+ --output-format stream-json # events on stdout
+ --input-format stream-json # user turns to stdin as JSON
+ --verbose # required with stream-json for full event detail
+ --ide # VSCode auto-connect via lockfile
--model <model>
- [--session-id <UUID> | --resume <UUID>]
- --max-turns <N>
- [--max-budget-usd <D>]
+ [--session-id <UUID> | --resume <UUID>] # mutually exclusive
--allowedTools <csv>
--permission-mode <mode>
[--append-system-prompt <text>]
[--effort <low|medium|high|xhigh|max>]
- [--fallback-model <model>]
[--add-dir <path>]* [--disallowedTools <csv>] [--agent <name>]
+ [--mcp-config <json>] [--strict-mcp-config]
```
+**Dropped from the pool path** (vs. the previous headless/`-p` shape):
+`-p`, `--print`, `--include-partial-messages`, `--include-hook-events`,
+`--max-turns`, `--max-budget-usd`, `--fallback-model`. The positional
+`-- "<prompt>"` is also never emitted — prompts arrive as JSON on
+stdin (`{"type":"user","message":{"role":"user","content":"..."}}\n`).
+`ClaudeTaskSpec` keeps the corresponding Pydantic fields for
+back-compat; they're silently dropped in `interactive_argv`.
+
All flags documented at
[code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference).
Worktree, lockfile, and bearer-token MCP server are wired in
-`session.py:_pre_spawn`; the `--ide` flag tells the CLI to discover that
-lockfile via `CLAUDE_IDE_LOCK`.
+`session_pool.py:_spawn`; the `--ide` flag tells the CLI to discover
+that lockfile via `CLAUDE_IDE_LOCK`.
+
+The non-pooled `AICliSession` path (one-shot prompt-in-argv runs that
+don't need session reuse) still uses PTY (`ptyprocess` POSIX /
+`pywinpty>=3.0.3` Windows) and remains out of scope for the
+subprocess+stream-json refactor.
Factory:
@@ -342,125 +358,114 @@ finds its own JSONL.
### Argv contract
-| Run state | Argv | Why |
+| Run state | Argv emitted | Why |
|---|---|---|
-| First run (no `last_session_id` in DB) | `--session-id <UUID5(memory_node_id, simpleMemory.session_id)>` | Deterministic UUID lets us address the same session predictably; survives session_id forks via the user-visible `simpleMemory.session_id` slot. |
-| Subsequent run (`last_session_id` saved) | `--resume <last_session_id>` | Native claude session resume. Same `cwd=repo_root` → same project_key → claude finds the JSONL it wrote on the previous turn. |
-| After "No conversation found" error | argv same as above on the spawn that errored; `_persist_memory` auto-clears `last_session_id` so the NEXT run falls into the first-run branch with `--session-id <UUID5>`. | Self-heal from a stale or wiped JSONL. |
+| First cold spawn under a memory-wired node | `--continue` | Claude auto-loads the most recent conversation under cwd's `project_key` (per [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference)). No UUID round-trip needed — claude tracks its own latest session per cwd on disk. |
+| Subsequent turn, SAME warm subprocess | nothing argv-level — stream-json line on `proc.stdin` | The pool keeps the subprocess alive between turns. Claude maintains the conversation in-process; same `session_id` across turns (verified end-to-end). |
+| Crash recovery (subprocess died between batches) | `--resume <captured_uuid>` | `ClaudeSessionPool.acquire` detects `process.returncode is not None`, captures the dead session's `current_session_uuid`, and respawns with `--resume`. Same `cwd=repo_root` → same `project_key` → claude finds the same JSONL it was writing before the crash. Mutually exclusive with `--continue`. |
Argv emission lives in
-`providers/anthropic_claude.py:headless_argv` — picks up
-`task.session_id` vs `task.resume_session_id` (mutually exclusive
-fields on `ClaudeTaskSpec`).
+[`providers/anthropic_claude.py:interactive_argv`](../server/services/cli_agent/providers/anthropic_claude.py).
+The `ClaudeTaskSpec` carries `continue_session: bool` and
+`resume_session_id: Optional[str]`. `claude_code_agent.execute_op` sets
+`continue_session = bool(memory_data)` for the cold-spawn case; the
+pool's crash-recovery path injects `resume_session_id =
+session.current_session_uuid` into the spec before respawning.
+`--session-id <UUID5>` (the pre-cutover UUID-round-trip primitive) is
+intentionally NOT emitted in interactive mode — claude rejects it.
### Plumbing
```
ClaudeCodeAgentNode.execute_op
- └─ collect_agent_connections() → memory_data {node_id, session_id,
- memory_content, window_size,
- long_term_enabled,
- last_session_id}
- └─ derive resume_session_id (= memory_data.last_session_id) OR
- first_run_session_uuid (= uuid5(NAMESPACE_OID,
- f"{memory_node_id}:{session_id}"))
- └─ ClaudeTaskSpec(..., session_id=..., resume_session_id=...)
- └─ run_batch(..., connected_memory=memory_data, broadcaster=...)
- └─ AICliService.run_batch:
- ├─ AICliSession(..., memory_bound=True) # ← drives cwd switch
- │ └─ cwd() returns self._repo_root
- │ └─ _pre_spawn skips `git worktree add`
- │ └─ cleanup skips `git worktree remove`
- └─ asyncio.gather → SessionResults
+ ├─ collect_agent_connections() → memory_data {node_id, session_id,
+ │ memory_content, window_size,
+ │ long_term_enabled,
+ │ last_session_id (display-only)}
+ ├─ continue_session = bool(memory_data)
+ ├─ ClaudeTaskSpec(..., continue_session=continue_session,
+ │ resume_session_id=None)
+ └─ AICliService.run_batch(..., connected_memory=memory_data,
+ broadcaster=...)
+ └─ For memory-wired runs, route through ClaudeSessionPool:
+ ├─ pool.acquire(memory_node_id, spec, cwd=repo_root, env, ...)
+ │ ├─ cold: spawn `claude --output-format stream-json
+ │ │ --input-format stream-json --verbose --ide
+ │ │ --continue ...` as subprocess with stdio pipes;
+ │ │ no PTY. stdout_reader_task parses each event line
+ │ │ and dispatches to _handle_stream_event.
+ │ └─ warm reuse: return the existing PooledClaudeSession;
+ │ the next prompt rides the same subprocess.
+ │ └─ crash recovery: capture current_session_uuid from the
+ │ dead session, splice resume_session_id
+ │ onto the spec, spawn fresh with --resume.
+ ├─ pool.send_turn(session, prompt):
+ │ ├─ write {"type":"user","message":{...}} + "\n" to proc.stdin
+ │ └─ await session.result_event (set by the stdout reader
+ │ when claude emits `result`)
+ ├─ pool.release(session) ← marks idle for the reaper
└─ _persist_memory(connected_memory, results, broadcaster):
├─ saves params["last_session_id"] = most_recent.session_id
+ │ (display-only — claude_code_agent no longer reads it)
├─ appends user/assistant turns to params["memory_content"]
│ via append_to_memory_markdown + trim_markdown_window
- │ (the same helpers aiAgent / chatAgent / deep_agent / rlm_agent
- │ use — reuse, don't duplicate)
├─ database.save_node_parameters(memory_node_id, params)
└─ broadcaster.broadcast({"type": "node_parameters_updated",
"node_id": memory_node_id, ...})
- # ← the UI's parameter panel auto-refreshes the moment
- # the run completes. Without this the DB has the
- # latest conversation but the UI keeps showing the
- # stale snapshot it loaded at workflow open.
```
-### Self-healing on stale UUID
-
-`AICliService._clear_stale_session_id(connected_memory)` substring-
-matches `"No conversation found with session ID"` in any result's
-`error`. When matched it wipes `simpleMemory.last_session_id` from
-the DB but preserves `memory_content` (the user-visible markdown
-transcript). Next run derives a fresh `--session-id <UUID5>` and
-proceeds with a clean session.
-
-Triggered automatically inside `_persist_memory` when zero results
-succeed. Without this the same stale UUID would re-fire every run
-and the user would be stuck.
-
### Parallel-batch guard
-Memory continuity requires serial execution — N concurrent
-`--resume <UUID>` spawns against one session JSONL would race. When
-`memory_data` is wired AND `len(tasks) > 1`, `claude_code_agent`
-raises `NodeUserError("Memory-bound batches must run one task at a
-time. Reduce Tasks to a single entry, or disconnect the memory
-node.")` at handler entry — never spawns.
+Memory continuity requires serial execution — N concurrent `--continue`
+spawns against the same `project_key` would race claude's
+session-resolution. When `memory_data` is wired AND `len(tasks) > 1`,
+`claude_code_agent` raises `NodeUserError("Memory-bound batches must
+run one task at a time. ...")` at handler entry.
### Markdown mirror
`memory_content` (the markdown surface the simpleMemory UI shows) is
-**a display mirror, not the canonical record**. Claude's own JSONL
-is canonical. `_persist_memory` appends each successful run's prompt
-+ response to `memory_content` via `append_to_memory_markdown` so the
-UI shows the conversation grow live. User edits to `memory_content`
-do NOT influence claude's next response — claude reads its own JSONL
-via `--resume`.
+a **display mirror**, not the resume channel. Claude's own JSONL on
+disk is what `--continue` and `--resume` load from. `_persist_memory`
+appends each successful run's prompt + response to `memory_content`
+via `append_to_memory_markdown` so the UI shows the conversation grow
+live. User edits to `memory_content` do NOT influence claude's next
+response.
To reset both: click the simpleMemory's clear button or invoke the
-`clear_memory` WS handler with `memory_node_id` — backend wipes
-`memory_content` to the default placeholder AND clears
-`last_session_id` in one DB write. Claude's on-disk JSONL is left
-alone (orphan, harmless). The next run with the same memory wired
-will spawn a fresh session at a NEW deterministic UUID5 (because
-the user's `simpleMemory.session_id` is part of the UUID5 inputs;
-unchanged after clear, but `last_session_id` being None routes us
-through the first-run branch).
+`clear_memory` WS handler — backend wipes `memory_content` to the
+default placeholder AND clears `last_session_id` in one DB write.
+Claude's on-disk JSONL is left alone (orphan, harmless). The next run
+spawns fresh with `--continue` against a project_key that has no
+matching prior session, and claude assigns a brand-new UUID.
### Logs to watch
```
-[Claude Code memory] memory_node=<id> last_session_id=<UUID|None>
- -> --resume <UUID> | --session-id <UUID5> (first run)
+[Claude Code memory] memory_node=<id> -> --continue
+ (claude auto-finds latest session under cwd)
[CC-Agent run_batch] enter ... memory=<memory_node_id> ...
-[AICliSession_*] memory-bound: skipping worktree, using cwd=<repo_root>
-
-[CC-Agent stream] result is_error=False subtype=success
- session_id=<UUID> duration_ms=...
+[ClaudeSessionPool] spawned new session memory_node=<id> pid=<N>
+ (cold spawn — argv carries --continue or --resume <UUID>)
+[ClaudeSessionPool] warm reuse memory_node=<id> pid=<N> uuid=<UUID>
+ (intra-process turn — stream-json on stdin)
-[CC-Agent _persist_memory] memory_node=<id> results=1 successful=1
- session_ids=['<UUID>']
[CC-Agent _persist_memory] saved memory_node=<id> last_session_id=<UUID>
appended_turns=1 archived_blocks=0 content_length=<N>
```
-On a stale-resume failure path the trace ends with:
+On a crash-recovery path the trace shows:
```
-[CC-Agent stderr] No conversation found with session ID: <UUID>
-[CC-Agent stream] result is_error=True subtype=error_during_execution
- session_id=<new-UUID-claude-assigned-to-the-failed-attempt>
-[CC-Agent _persist_memory] no successful runs; skipping save ...
-[CC-Agent _persist_memory] cleared stale last_session_id=<UUID>
- from memory_node=<id>; next run will spawn a fresh claude session
- and persist its new UUID.
-```
+[ClaudeSessionPool] dropping dead session memory_node=<id>
+ pid=<dead-pid> exit=<code> — will respawn
-— and the next run succeeds with `--session-id <UUID5>`.
+[ClaudeSessionPool] spawned new session memory_node=<id> pid=<new-pid>
+ (argv: --resume <UUID> taken from the dead session's
+ current_session_uuid; same project_key, same JSONL continues)
+```
## Status broadcast events
diff --git a/server/nodes/agent/claude_code_agent/__init__.py b/server/nodes/agent/claude_code_agent/__init__.py
index 4fdb7ef5..9d95ac1b 100644
--- a/server/nodes/agent/claude_code_agent/__init__.py
+++ b/server/nodes/agent/claude_code_agent/__init__.py
@@ -19,7 +19,7 @@ from __future__ import annotations
import time
from datetime import datetime
from pathlib import Path
-from typing import Any, List, Optional
+from typing import Any, List, Literal, Optional
from pydantic import BaseModel, ConfigDict, Field, field_validator
@@ -38,42 +38,110 @@ from services.cli_agent import ClaudeTaskSpec # noqa: E402
from services.cli_agent.types import SessionResultModel # noqa: E402
+# Claude Code-supported models. Per
+# https://code.claude.com/docs/en/cli-reference the ``--model`` flag
+# accepts either an Anthropic-managed alias (``sonnet`` / ``opus`` /
+# ``haiku`` — resolves to the latest in that family) or a full model ID.
+# We surface both so users can pin a specific revision OR float to the
+# tier-latest. Free-text ``str`` was the prior type; switching to
+# ``Literal`` gives the parameter panel a dropdown without losing
+# back-compat (every value the field used to accept is still in the list).
+ClaudeCodeModel = Literal[
+ # Anthropic-managed aliases — track the freshest model per family
+ "sonnet",
+ "opus",
+ "haiku",
+ # Pinned full IDs — current generation (Claude 4.x)
+ "claude-opus-4-7",
+ "claude-opus-4-6",
+ "claude-opus-4-5",
+ "claude-opus-4-1",
+ "claude-opus-4",
+ "claude-sonnet-4-6",
+ "claude-sonnet-4-5",
+ "claude-sonnet-4",
+ "claude-haiku-4-5",
+]
+
+
+ClaudeCodeEffort = Literal["low", "medium", "high", "xhigh", "max"]
+
+
class ClaudeCodeAgentParams(BaseModel):
- """Multi-task batch parameters for Claude Code.
+ """Claude Code node parameters.
+
+ UI surface: a single ``prompt`` field. Every other field is kept on
+ the model for back-compat with existing saved workflows and to feed
+ sensible defaults into the per-task ``ClaudeTaskSpec`` — but is
+ hidden from the parameter panel via ``json_schema_extra.hidden``
+ so the canvas-side surface stays minimal.
- Two paths:
- 1. ``tasks=[...]`` — explicit list, runs N in parallel
- 2. ``tasks=[]`` + legacy ``prompt`` — synthesises a single-task batch
+ Two execution paths (both invisible to the user):
+ 1. ``tasks=[...]`` — explicit list (advanced; saved workflows only)
+ 2. ``tasks=[]`` + ``prompt`` — synthesises a single-task batch (default)
"""
- tasks: List[ClaudeTaskSpec] = Field(
- default_factory=list,
- description="List of Claude tasks to run in parallel (max 5 concurrent).",
- json_schema_extra={"rows": 1},
- )
- # Legacy single-task fallback ----------------------------------------
+ # The ONLY visible field. Everything below is ``hidden: true``.
prompt: str = Field(
default="",
- description="Legacy: single-prompt fallback used only when "
- "`tasks` is empty.",
- json_schema_extra={"rows": 4, "placeholder": "Or use the tasks array..."},
+ description="The prompt sent to Claude Code.",
+ json_schema_extra={"rows": 4, "placeholder": "Ask Claude Code to..."},
+ )
+
+ # --- Hidden: advanced multi-task batch ---
+ tasks: List[ClaudeTaskSpec] = Field(
+ default_factory=list,
+ description="Advanced: list of Claude tasks to run in parallel "
+ "(max 5 concurrent). Use ``prompt`` for the common case.",
+ json_schema_extra={"hidden": True, "rows": 1},
)
- model: str = Field(
+
+ # --- Hidden: model + system prompt + execution scoping ---
+ model: ClaudeCodeModel = Field(
default="claude-sonnet-4-6",
- description="Default model for tasks that don't override it.",
+ description=(
+ "Default model for tasks that don't override it. Aliases "
+ "(``sonnet`` / ``opus`` / ``haiku``) resolve to the latest in "
+ "each family; full IDs pin a specific revision."
+ ),
+ json_schema_extra={"hidden": True},
+ )
+ system_prompt: Optional[str] = Field(
+ default=None,
+ json_schema_extra={"hidden": True, "rows": 3},
)
- system_prompt: Optional[str] = Field(default=None, json_schema_extra={"rows": 3})
working_directory: Optional[str] = Field(
default=None,
description="Git repo root. Defaults to the workflow's workspace dir.",
+ json_schema_extra={"hidden": True},
)
max_parallel: int = Field(
default=5, ge=1, le=20,
description="Concurrency cap.",
+ json_schema_extra={"hidden": True},
)
allowed_credentials: List[str] = Field(
default_factory=list,
description="Credential names the CLI is permitted to fetch via MCP.",
+ json_schema_extra={"hidden": True},
+ )
+
+ # --- Hidden: model knobs (effort, fallback) ---
+ effort: Optional[ClaudeCodeEffort] = Field(
+ default=None,
+ description=(
+ "Reasoning-effort level passed via ``--effort``. Applies to "
+ "thinking-capable models (Opus / Sonnet); ignored by Haiku."
+ ),
+ json_schema_extra={"hidden": True},
+ )
+ fallback_model: Optional[ClaudeCodeModel] = Field(
+ default=None,
+ description=(
+ "Model to fall back to when the primary is overloaded. "
+ "Passed via ``--fallback-model``."
+ ),
+ json_schema_extra={"hidden": True},
)
# Saved workflow JSON may persist these list fields as `null` rather
@@ -219,6 +287,10 @@ class ClaudeCodeAgentNode(ActionNode):
"system_prompt": params.system_prompt,
"continue_session": continue_session,
}
+ if params.effort is not None:
+ spec_kwargs["effort"] = params.effort
+ if params.fallback_model is not None:
+ spec_kwargs["fallback_model"] = params.fallback_model
tasks = [ClaudeTaskSpec(**spec_kwargs)]
else:
# Apply node-level defaults to tasks that don't override.
@@ -228,6 +300,10 @@ class ClaudeCodeAgentNode(ActionNode):
changed["model"] = params.model
if not t.system_prompt and params.system_prompt:
changed["system_prompt"] = params.system_prompt
+ if t.effort is None and params.effort is not None:
+ changed["effort"] = params.effort
+ if t.fallback_model is None and params.fallback_model is not None:
+ changed["fallback_model"] = params.fallback_model
# Only auto-enable --continue when memory is wired AND
# the task didn't explicitly opt in/out or pick a UUID.
if (
diff --git a/server/services/cli_agent/jsonl_watcher.py b/server/services/cli_agent/jsonl_watcher.py
index c0962884..bb129ec5 100644
--- a/server/services/cli_agent/jsonl_watcher.py
+++ b/server/services/cli_agent/jsonl_watcher.py
@@ -323,6 +323,38 @@ class JsonlDirWatcher:
pass
+def snapshot_jsonl_sizes(project_dir: Path) -> Dict[str, int]:
+ """Return ``{name: size_bytes}`` for every ``.jsonl`` in ``project_dir``.
+
+ Used by ``ClaudeSessionPool._wait_for_session_jsonl`` (and the
+ equivalent in :class:`AICliSession`) to baseline the project dir
+ before spawning ``claude``. Post-spawn the caller polls again and
+ picks whichever file is new (absent from baseline) or grew
+ (``current_size > baseline_size``) — both fresh spawns and
+ ``--continue`` spawns produce a size-positive delta.
+
+ Returns an empty dict if ``project_dir`` doesn't exist yet (first
+ spawn under a new cwd). Silently skips entries the filesystem
+ refuses to ``stat`` — they're typically transient and the post-spawn
+ poll will catch them on the next tick once they settle.
+ """
+ sizes: Dict[str, int] = {}
+ try:
+ entries = list(project_dir.iterdir())
+ except (FileNotFoundError, NotADirectoryError):
+ return sizes
+ except OSError:
+ return sizes
+ for entry in entries:
+ if entry.suffix != ".jsonl":
+ continue
+ try:
+ sizes[entry.name] = entry.stat().st_size
+ except OSError:
+ continue
+ return sizes
+
+
def session_uuid_from_jsonl_path(path: Path) -> Optional[str]:
"""Extract the session UUID from a JSONL filename, or None if the
name doesn't match the ``<uuid>.jsonl`` convention.
diff --git a/server/services/cli_agent/providers/anthropic_claude.py b/server/services/cli_agent/providers/anthropic_claude.py
index c049c647..c8c668d9 100644
--- a/server/services/cli_agent/providers/anthropic_claude.py
+++ b/server/services/cli_agent/providers/anthropic_claude.py
@@ -108,30 +108,40 @@ class AnthropicClaudeProvider:
connected_tool_names: Optional[List[str]] = None,
include_prompt: bool = True,
) -> List[str]:
- """Build the full argv (binary + flags) for one interactive task.
-
- Emits the same invocation a human user runs (``claude ... --
- "<prompt>"``) rather than ``claude -p``. The TUI is held alive
- by a PTY; events are read from the on-disk JSONL at
- ``<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session>.jsonl``.
+ """Build the full argv for one ``claude`` invocation, VSCode-style.
+
+ Spawned as a regular subprocess with stdio pipes — NOT a PTY.
+ Matches the invocation Anthropic's own VSCode extension uses
+ (verified in
+ ``C:\\Users\\Tgroh\\.vscode\\extensions\\anthropic.claude-code-2.1.140-win32-x64\\extension.js``
+ line 156):
+
+ ``claude --output-format stream-json --input-format stream-json
+ --verbose --ide [task-flags...]``
+
+ User prompts arrive over ``proc.stdin`` as newline-delimited JSON
+ of shape ``{"type":"user","message":{"role":"user","content":...}}``,
+ not as an argv positional. Events stream back on ``proc.stdout``
+ in the same shape claude writes to its on-disk JSONL — the FE-
+ facing event handlers downstream are file-source-agnostic so
+ we keep tailing the JSONL via ``JsonlWatcher`` either way.
+
+ Critically NOT emitted:
+
+ - ``-p`` / ``--print``: keeps us in the interactive billing
+ bucket (entrypoint ``claude-vscode``, NOT ``sdk-cli``). The
+ VSCode extension confirms this exact pattern works without
+ ``--print``.
+ - The positional prompt (``-- "<prompt>"``): the prompt
+ arrives via ``proc.stdin`` in stream-json input mode.
+ ``include_prompt`` is kept for back-compat but ignored.
``mcp_endpoint_url`` + ``mcp_bearer_token`` (if both set) are
- emitted as a ``--mcp-config <json>`` block so the spawned
- ``claude`` registers MachinaOs's FastMCP server (works
- identically in interactive + headless modes per
- https://code.claude.com/docs/en/mcp).
-
- Tools and skills are unchanged from the prior headless path —
- same ``--allowedTools`` list (built-ins + every wired
- ``mcp__machinaos__*``), same skill materialisation under
- ``<cwd>/.claude/skills/`` (in ``AICliSession._materialise_skills``).
- The permission flag flips from ``acceptEdits`` to
- ``bypassPermissions`` so non-Edit tools in the allowlist fire
- without prompting the TUI (no human to click "Allow").
-
- ``include_prompt=False`` is used by the session pool when
- respawning a fresh process whose first prompt will be written
- to the PTY rather than passed on argv (e.g. after a `/clear`).
+ emitted as ``--mcp-config <json>`` so the spawned claude
+ registers MachinaOs's FastMCP server. Tools allowlist
+ (``--allowedTools``) lists every wired ``mcp__machinaos__*``
+ plus the 5 built-ins. Skill materialisation under
+ ``<cwd>/.claude/skills/`` is unchanged.
"""
if not isinstance(task, ClaudeTaskSpec):
raise TypeError(
@@ -141,6 +151,23 @@ class AnthropicClaudeProvider:
argv: List[str] = [str(self.binary_path())]
+ # Stream-json I/O — the VSCode extension pattern. Prompts go via
+ # ``proc.stdin``, events come back on ``proc.stdout``. Verified
+ # against
+ # ``$VSCODE_EXT_DIR/anthropic.claude-code-<ver>/extension.js:156``
+ # which spawns claude with exactly these four flags. ``--verbose``
+ # is required so the stream-json output includes the full event
+ # detail (without it, only the final result line is emitted).
+ # ``--ide`` makes claude discover the IDE lockfile we write at
+ # ``<CLAUDE_CONFIG_DIR>/ide/<pid>.lock`` for auto-connection to
+ # MachinaOs's MCP server.
+ argv += [
+ "--output-format", "stream-json",
+ "--input-format", "stream-json",
+ "--verbose",
+ "--ide",
+ ]
+
# MCP server registration — same shape as the prior headless
# path; the Claude Code MCP doc's ``mcp.json`` example. Works
# identically in interactive mode.
@@ -270,13 +297,13 @@ class AnthropicClaudeProvider:
if task.agent:
argv += ["--agent", task.agent]
- # Prompt as positional argument after `--`. Claude auto-submits
- # the positional as turn 1 and stays interactive (per
- # https://code.claude.com/docs/en/cli-reference). The session
- # pool sets include_prompt=False for spawns whose first prompt
- # will be written to the PTY directly.
- if include_prompt and task.prompt:
- argv += ["--", task.prompt]
+ # Prompt arrives via ``proc.stdin`` as stream-json — NOT as
+ # an argv positional. ``include_prompt`` is kept on the signature
+ # for back-compat (older callers pass ``include_prompt=False``)
+ # but is ignored: stream-json input mode and a positional prompt
+ # would double-send the first turn. Caller writes prompts to
+ # ``ClaudeSessionPool.send_turn``'s ``proc.stdin`` instead.
+ _ = include_prompt
return argv
@@ -371,6 +398,35 @@ class AnthropicClaudeProvider:
success = False
error = error or response or "result event reports error"
+ # Surface routable extras on ``provider_data`` so downstream
+ # workflow nodes can read them off ``tasks[i].provider_data.*``.
+ # ``canonical_usage`` flattens token counts across all models;
+ # ``modelUsage`` preserves the per-model breakdown (with the
+ # per-model ``costUSD`` + ``contextWindow`` + ``maxOutputTokens``
+ # claude itself reports). The minor fields below either drive
+ # FE diagnostics (``terminal_reason`` / ``api_error_status``)
+ # or feed cost analytics (``service_tier`` / ``inference_geo``
+ # land inside the usage block but aren't propagated by
+ # ``canonical_usage`` because that struct is per-event, not
+ # per-result).
+ for key in (
+ "modelUsage",
+ "permission_denials",
+ "terminal_reason",
+ "fast_mode_state",
+ "api_error_status",
+ ):
+ if key in final and final[key] is not None:
+ provider_data.setdefault(key, final[key])
+ # Pull the service-tier / cache-creation / inference-geo bits
+ # off the usage block so downstream consumers don't have to
+ # re-iterate the events themselves.
+ usage_block = final.get("usage") or {}
+ for key in ("service_tier", "inference_geo"):
+ v = usage_block.get(key)
+ if v:
+ provider_data.setdefault(key, v)
+
cu = self.canonical_usage(events)
return {
diff --git a/server/services/cli_agent/session.py b/server/services/cli_agent/session.py
index 8ca0178c..395ba309 100644
--- a/server/services/cli_agent/session.py
+++ b/server/services/cli_agent/session.py
@@ -49,7 +49,7 @@ import yaml
from core.logging import get_logger
from services._supervisor.process import BaseProcessSupervisor
-from services.cli_agent.jsonl_watcher import JsonlWatcher
+from services.cli_agent.jsonl_watcher import JsonlWatcher, snapshot_jsonl_sizes
from services.cli_agent.lockfile import remove_ide_lockfile, write_ide_lockfile
from services.cli_agent.protocol import AICliProvider, CanonicalUsage, SessionResult
from services.cli_agent.transports import PtyHandle, get_pty_transport
@@ -273,7 +273,16 @@ class AICliSession(BaseProcessSupervisor):
connected skill so the spawned claude can invoke them via the
built-in `Skill` tool. Filesystem skills are copied wholesale
(preserves `scripts/` + `references/`); DB skills are
- reconstructed from frontmatter."""
+ reconstructed from frontmatter.
+
+ Only ``AICliSession`` (the non-pooled, one-shot agent path)
+ calls this. ``ClaudeSessionPool`` (the pooled, memory-bound
+ path) leaves skills accessible via the FastMCP server's
+ ``listSkills``/``getSkill`` tools instead. Switching the pool
+ to the standard ``--add-dir`` skill discovery is tracked
+ separately (requires restructuring ``server/skills/`` to the
+ Agent Skills `<root>/.claude/skills/<name>/SKILL.md` shape).
+ """
from services.skill_loader import get_skill_loader
loader = get_skill_loader()
@@ -382,15 +391,13 @@ class AICliSession(BaseProcessSupervisor):
# Resume runs: known location. Claude opens this file and
# appends to it on each turn.
self._session_jsonl_path = project_dir / f"{resume_uuid}.jsonl"
- # Else: post-spawn we'll discover the file via mtime — works
- # uniformly for fresh-spawn (claude creates new) and
- # --continue (claude appends to existing).
-
- # Spawn via the cross-platform PTY transport. The PtyHandle
- # owns the subprocess; `self._proc` stays `None` for
- # BaseProcessSupervisor-compat — `is_running` / `_do_stop` are
- # overridden below to consult `self._pty_handle` instead.
- spawn_time = time.monotonic()
+
+ # Snapshot every existing JSONL's size BEFORE spawn so the post-spawn
+ # locator can detect "claude wrote here" via deterministic size-diff —
+ # works uniformly for fresh spawns (new filename) AND ``--continue``
+ # spawns (existing file grows). Size is monotonic and filesystem-
+ # portable; mtime / wall-clock comparisons are not.
+ baseline_sizes = snapshot_jsonl_sizes(project_dir)
transport = get_pty_transport()
argv = self.argv()
try:
@@ -412,14 +419,14 @@ class AICliSession(BaseProcessSupervisor):
# Resolve the JSONL path. For known-UUID `--resume` runs the
# path is already known; otherwise (fresh OR `--continue`)
- # discover via mtime — claude either creates a new file (fresh)
- # or updates the latest existing file's mtime by appending an
- # init event (--continue). Either way "newest .jsonl with
- # mtime >= spawn_time - grace" is the right file.
+ # discover via size-diff against the pre-spawn baseline: claude
+ # either creates a new file (fresh) or appends an init event to
+ # the existing latest file (--continue). Either way, the first
+ # ``.jsonl`` whose size > baseline is the right file.
if self._session_jsonl_path is None:
try:
self._session_jsonl_path = await self._wait_for_session_jsonl(
- project_dir, spawn_time,
+ project_dir, baseline_sizes,
)
except TimeoutError as exc:
# Surface a clean error envelope rather than letting the
@@ -464,42 +471,33 @@ class AICliSession(BaseProcessSupervisor):
return Path(MACHINA_CLAUDE_DIR) / "projects" / project_key
async def _wait_for_session_jsonl(
- self, project_dir: Path, spawn_time: float,
+ self, project_dir: Path, baseline: Dict[str, int],
) -> Path:
- """Find the JSONL claude is using post-spawn via mtime.
+ """Find the JSONL claude is using post-spawn via size-diff vs baseline.
- Works for both fresh-spawn (claude creates a new file) and
- ``--continue`` (claude appends an init event to the most
- recent existing file, updating its mtime). Picks the newest
- ``.jsonl`` whose mtime is at least ``spawn_time - 1s``
- (1s grace for clock skew + mtime resolution).
+ ``baseline`` is the ``{name: size}`` snapshot taken BEFORE the
+ spawn. After spawn we poll for the first ``.jsonl`` that's
+ either new (not in baseline) or grown (size > baseline size).
+ Handles both fresh spawns (new filename) and ``--continue``
+ spawns (existing file grows). File size is a monotonic,
+ filesystem-portable signal — no wall-clock vs monotonic clock
+ comparison, no mtime-resolution races.
Raises :class:`TimeoutError` after
- :data:`_FIRST_RUN_JSONL_TIMEOUT` seconds — surfaces as a
- clean spawn failure rather than a silently dead session.
+ :data:`_FIRST_RUN_JSONL_TIMEOUT` seconds — surfaces as a clean
+ spawn failure rather than a silently dead session.
"""
- deadline = spawn_time + _FIRST_RUN_JSONL_TIMEOUT
- mtime_floor = spawn_time - 1.0 # grace for clock skew
- while time.monotonic() < deadline:
- try:
- jsonls = [
- p for p in project_dir.iterdir()
- if p.suffix == ".jsonl"
- ]
- except OSError:
- jsonls = []
- if jsonls:
- try:
- newest = max(jsonls, key=lambda p: p.stat().st_mtime)
- if newest.stat().st_mtime >= mtime_floor:
- return newest
- except OSError:
- pass
+ deadline_mono = time.monotonic() + _FIRST_RUN_JSONL_TIMEOUT
+ while time.monotonic() < deadline_mono:
+ current = snapshot_jsonl_sizes(project_dir)
+ for name, size in current.items():
+ if size > baseline.get(name, 0):
+ return project_dir / name
await asyncio.sleep(0.1)
raise TimeoutError(
- f"No session JSONL touched under {project_dir} within "
- f"{_FIRST_RUN_JSONL_TIMEOUT}s — claude may have failed to "
- f"start or the CLAUDE_CONFIG_DIR is misconfigured."
+ f"No session JSONL appeared or grew under {project_dir} "
+ f"within {_FIRST_RUN_JSONL_TIMEOUT}s — claude may have "
+ f"failed to start or the CLAUDE_CONFIG_DIR is misconfigured."
)
async def _on_jsonl_event(self, event: Dict[str, Any]) -> None:
diff --git a/server/services/cli_agent/session_pool.py b/server/services/cli_agent/session_pool.py
index 50a08006..55685947 100644
--- a/server/services/cli_agent/session_pool.py
+++ b/server/services/cli_agent/session_pool.py
@@ -1,41 +1,73 @@
-"""Warm-process pool for interactive ``claude`` sessions.
-
-Keeps a live ``claude`` PTY per ``simpleMemory.node_id`` so successive
-turns can reuse the warm process — the PTY stays alive across batches
-and the next prompt rides on the existing claude session (saves the
-~1-2 s spawn cost). By default acquire is **non-disruptive**: warm
-reuse returns the same session UUID, so the memory bridge's
-conversation continuity stays intact (claude appends to its existing
-JSONL).
-
-Context reset is an **explicit** operation via :meth:`clear`. ``/clear``
-mints a NEW session UUID with a NEW JSONL file — per issue
-`claude-code#32871 <https://github.com/anthropics/claude-code/issues/32871>`_
-— so calling it is the right primitive when the user wants to start a
-fresh conversation in the same pooled process (e.g. a "Clear
-conversation" button on simpleMemory). The memory bridge auto-picks
-up the new UUID from the next turn's ``result`` event.
+"""Long-lived ``claude`` subprocess pool — VSCode-extension pattern.
+
+Keeps one warm ``claude --output-format stream-json --input-format
+stream-json --verbose --ide`` subprocess per ``simpleMemory.node_id``
+so successive turns can reuse the same process — same session UUID
+across turns, no respawn cost. Mirrors what Anthropic's official
+VSCode extension does (verified from the on-disk extension source at
+``$VSCODE_EXT_DIR/anthropic.claude-code-<ver>/extension.js`` line 156).
+
+Why subprocess (not PTY): pywinpty's ConPTY emulation does not deliver
+keystrokes to claude's Ink TUI on Windows — empirically confirmed
+across four test variants (`docs-internal/claude_code_interactive_mode.md`
+records the post-mortem). Plain stdio pipes work cross-platform and
+match the documented multi-turn integration pattern.
+
+Per-turn mechanics:
+
+ 1. Caller writes one stream-json line to ``proc.stdin``:
+ ``{"type":"user","message":{"role":"user","content":"..."}}\\n``
+ 2. Claude reads stdin, processes the turn, emits stream-json events
+ to ``proc.stdout`` (``system/init``, ``assistant``, ``user``,
+ ``system/compact_boundary``, and finally ``result``). Claude
+ ALSO writes a subset of events to the on-disk session JSONL at
+ ``<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_uuid>.jsonl``
+ for persistent multi-batch memory — but the ``result`` event is
+ stdout-only in stream-json mode, so stdout is our runtime contract.
+ 3. A background ``stdout_reader_task`` started at spawn time parses
+ each line as a stream-json event and dispatches via
+ :meth:`_handle_stream_event`. Events flow into the per-turn
+ buffer; ``result_event`` fires when the final ``type=="result"``
+ event lands.
+ 4. ``send_turn`` returns a :class:`SessionResult` built from the
+ turn's events. The session UUID is captured from the result event
+ so subsequent batches can spawn ``--resume <UUID>`` if the
+ pooled process has been reaped.
Lifecycle policy:
- - **Idle TTL**: 30 min default. A background reaper task terminates
- pooled sessions whose ``last_used_at`` exceeds the threshold.
- - **Max size**: 16 default. LRU eviction when full.
- - **Crash recovery**: ``acquire()`` checks ``is_alive()`` and respawns
- transparently when the pooled PTY has died.
- - **Concurrency**: per-key ``asyncio.Lock`` serialises turns against
- the same pooled session (the existing parallel-batch guard in
- ``claude_code_agent`` enforces N=1 per memory node, so the lock is
- a belt-and-braces invariant).
- - **Shutdown**: ``ClaudeSessionPool.shutdown_all()`` terminates every
- pooled PTY. Wire into FastAPI's lifespan hook.
-
-Pattern mirrors :mod:`services.process_service` (long-lived process pool)
-and :mod:`nodes.telegram._service` (singleton service with lifecycle).
+
+ - **Idle TTL**: 30 min default. Background reaper terminates
+ long-idle subprocesses.
+ - **Max size**: 16 concurrent pooled sessions. LRU eviction at cap.
+ - **Crash recovery**: ``acquire()`` checks ``process.returncode`` and
+ respawns transparently when the pooled subprocess has died.
+ - **Per-session lock**: serialises turns against the same pooled
+ process so two ``send_turn`` calls don't write overlapping
+ stream-json lines.
+ - **Shutdown**: :meth:`shutdown_all` closes every subprocess's stdin
+ (claude exits cleanly on EOF) and waits briefly, then kills any
+ holdouts. Wire into FastAPI's lifespan ``shutdown`` event.
+
+Continuity across process restarts:
+
+ - First spawn for a memory-bound run: argv emits ``--continue``
+ (claude resolves the latest conversation under cwd's
+ ``project_key`` automatically; works whether or not a prior
+ JSONL exists).
+ - Each successful turn captures ``result.session_id`` onto
+ ``session.current_session_uuid``. If the subprocess is later
+ reaped and a new ``acquire`` happens, the next spawn emits
+ ``--resume <session.current_session_uuid>`` so the SAME JSONL
+ keeps growing across process restarts.
+ - :meth:`clear` is an explicit context-reset primitive: kill the
+ subprocess, drop the captured UUID, let the next ``acquire``
+ spawn fresh with no continuity flag (claude assigns a new UUID).
"""
from __future__ import annotations
import asyncio
+import json
import time
import uuid
from dataclasses import dataclass, field
@@ -44,79 +76,81 @@ from typing import Any, Dict, List, Literal, Optional
from core.logging import get_logger
from services.cli_agent.factory import create_cli_provider
-from services.cli_agent.jsonl_watcher import (
- JsonlDirWatcher,
- JsonlWatcher,
- session_uuid_from_jsonl_path,
-)
from services.cli_agent.protocol import AICliProvider, SessionResult
-from services.cli_agent.transports import PtyHandle, get_pty_transport
from services.cli_agent.types import ClaudeTaskSpec
logger = get_logger(__name__)
-# Defaults — keep aligned with the operator's mental model. The 30 min
-# idle TTL matches a typical "I switched tasks but might come back"
-# workflow; 16 concurrent pooled sessions matches the FastAPI default
-# worker count.
+# Defaults — keep aligned with the operator's mental model.
_DEFAULT_IDLE_TTL = 30 * 60.0
_DEFAULT_MAX_SIZE = 16
_DEFAULT_REAPER_INTERVAL = 60.0 # reaper tick
-# How long to wait for the new JSONL file to appear after sending
-# ``/clear``. Empirically ~200 ms on Linux; 5 s is a generous cap that
-# matches the first-spawn JSONL-locate timeout in ``AICliSession``.
-_CLEAR_JSONL_TIMEOUT = 5.0
+# Soft window for stdin EOF to drive a graceful claude shutdown before
+# we escalate to ``proc.kill()``. Claude exits within ~100 ms of EOF.
+_SHUTDOWN_GRACE = 2.0
@dataclass
class PooledClaudeSession:
- """One live ``claude`` PTY + the metadata to reuse it across turns.
-
- Owns the PTY transport handle, the current ``JsonlWatcher``, and a
- persistent ``JsonlDirWatcher`` over the project dir (used to detect
- the new UUID claude assigns after each ``/clear``).
+ """One live ``claude`` subprocess + the metadata to reuse it across turns.
+
+ No PTY, no file watcher. ``process`` is an ``asyncio.subprocess.Process``
+ opened with ``stdin=PIPE``, ``stdout=PIPE``, ``stderr=PIPE``. Prompts
+ go via ``process.stdin.write(stream_json_line)``; events come back on
+ ``process.stdout`` (stream-json output mode), parsed line-by-line by
+ a background ``stdout_reader_task`` that dispatches each parsed event
+ via :meth:`ClaudeSessionPool._handle_stream_event`. Stderr is drained
+ separately and logged.
+
+ The on-disk JSONL at
+ ``<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_uuid>.jsonl``
+ is still written by claude — it's the persistence layer that
+ ``--continue`` / ``--resume`` rehydrate from across process
+ restarts — but the runtime contract here is stdout-only because
+ the ``result`` event (final turn outcome) goes ONLY to stdout in
+ stream-json mode, NOT to the JSONL file.
"""
memory_node_id: str
- project_dir: Path
- pty_handle: PtyHandle
- current_session_uuid: str
- current_jsonl_path: Path
- dir_watcher: JsonlDirWatcher
- jsonl_watcher: JsonlWatcher
+ process: asyncio.subprocess.Process
cwd: Path
- # MCP bearer token embedded in the spawned claude's `--mcp-config`.
- # Set by the caller at spawn time so the warm-reuse path can read
- # it back and re-register the batch context with the SAME token
- # the live claude already has in its argv. The pool does NOT
- # issue/unregister tokens — the CLI handles its own MCP auth, the
- # caller (run_batch) owns the lifecycle.
- bearer_token: str = ""
+ # ``current_session_uuid`` is "" until the first turn's ``system/init``
+ # or ``result`` event reveals it. Subsequent spawns for the same
+ # memory_node_id (after a crash / reap) emit ``--resume <UUID>`` so
+ # the same on-disk JSONL keeps growing across process restarts.
+ current_session_uuid: str = ""
last_used_at: float = field(default_factory=time.monotonic)
- # Per-session lock; held throughout a turn or a /clear rotation. The
- # reaper consults ``lock.locked()`` to skip in-flight sessions — no
- # separate in_flight flag needed.
+ # Per-session lock; held throughout a turn. The reaper consults
+ # ``lock.locked()`` to skip in-flight sessions.
lock: asyncio.Lock = field(default_factory=asyncio.Lock)
- # Set by the JSONL handler when claude writes a ``result`` event;
+ # Set by the stdout reader when claude emits a ``result`` event;
# ``send_turn`` awaits this. Cleared before each new turn.
result_event: asyncio.Event = field(default_factory=asyncio.Event)
- # Per-turn event buffer, cleared on each ``send_turn`` so the result
- # builder only sees the current turn's events.
+ # Per-turn event buffer, cleared on each ``send_turn``.
events_this_turn: List[Dict[str, Any]] = field(default_factory=list)
- # Dir-watcher signal for ``/clear``: fires when a new ``.jsonl``
- # appears under ``project_dir``.
- new_jsonl_event: asyncio.Event = field(default_factory=asyncio.Event)
- new_jsonl_path: Optional[Path] = None
+ # Background tasks: parse stream-json events from stdout (single
+ # source of truth for runtime events), drain stderr (logged at
+ # warning level).
+ stdout_reader_task: Optional[asyncio.Task[None]] = None
+ stderr_drain_task: Optional[asyncio.Task[None]] = None
class ClaudeSessionPool:
- """Per-``memory_node_id`` pool of warm ``claude`` PTYs.
-
- Acquired via :meth:`acquire` (auto-spawns if missing, sends
- ``/clear`` + captures new UUID if reusing). Released via
- :meth:`release` (marks idle for the reaper).
+ """Per-``memory_node_id`` pool of warm ``claude`` subprocesses.
+
+ Public surface (unchanged from the PTY-era pool — callers in
+ :mod:`services.cli_agent.service` see the same method shapes):
+
+ - :meth:`acquire` — get or spawn a session for a memory_node_id
+ - :meth:`send_turn` — write one stream-json user message, return result
+ - :meth:`release` — mark idle for the reaper
+ - :meth:`clear` — kill subprocess + drop UUID (next acquire spawns fresh)
+ - :meth:`terminate` — force-drop a specific entry
+ - :meth:`shutdown_all` — drop everything (FastAPI lifespan hook target)
+ - :meth:`peek` — read-only inspection
+ - :meth:`start_reaper` — begin background idle-eviction
"""
def __init__(
@@ -130,8 +164,6 @@ class ClaudeSessionPool:
self._idle_ttl = float(idle_ttl)
self._max_size = int(max_size)
self._reaper_interval = float(reaper_interval)
- # Top-level lock guards `self._pool` mutations only (insert,
- # evict). Per-session turns serialise via `PooledClaudeSession.lock`.
self._pool_lock = asyncio.Lock()
self._reaper_task: Optional[asyncio.Task[None]] = None
self._shutdown = asyncio.Event()
@@ -151,19 +183,11 @@ class ClaudeSessionPool:
)
def peek(self, memory_node_id: str) -> Optional[PooledClaudeSession]:
- """Return the live session for ``memory_node_id`` or ``None``.
-
- Useful for callers that need to know whether to issue a fresh
- MCP bearer token before :meth:`acquire`. ``None`` means either
- no entry or the entry's PTY has died (caller should issue a
- fresh token for the impending cold-spawn). Best-effort: a TOCTOU
- race between this check and a concurrent :meth:`acquire` is
- harmless — the orphaned token leaks until app shutdown.
- """
+ """Return the live session for ``memory_node_id`` or ``None``."""
session = self._pool.get(memory_node_id)
if session is None:
return None
- if not session.pty_handle.is_alive():
+ if session.process.returncode is not None:
return None
return session
@@ -183,83 +207,77 @@ class ClaudeSessionPool:
"""Return a live :class:`PooledClaudeSession`.
Behaviour:
- - **No live entry**: spawn fresh. ``spec.prompt`` is *not*
- included in argv (the caller writes it via
- :meth:`send_turn` once the watcher is attached).
- - **Live entry**: return as-is. The next :meth:`send_turn`
- writes the prompt to the existing PTY; claude appends to
- its current JSONL so the conversation continues in the
- same session UUID. **No implicit ``/clear``** — that would
- break the memory bridge's continuity contract. The caller
- can explicitly call :meth:`clear` to reset context (mints
- a new UUID via ``/clear`` and swaps the watcher).
- - **Dead entry**: drop and spawn fresh.
-
- Caller MUST call :meth:`release` (or use the contextmanager
- wrapper) so the reaper can free idle sessions.
+
+ - No live entry → spawn fresh.
+ - Live entry whose subprocess is dead → drop and respawn,
+ propagating ``current_session_uuid`` so the new spawn
+ emits ``--resume <UUID>`` and continues the same JSONL.
+ - Live entry with live subprocess → return as-is. Next
+ ``send_turn`` writes the prompt to the existing subprocess's
+ stdin and claude appends to the same session JSONL.
+
+ Caller MUST call :meth:`release` so the reaper can mark idle.
"""
async with self._pool_lock:
existing = self._pool.get(memory_node_id)
- if existing is not None and not existing.pty_handle.is_alive():
+ crashed_uuid = ""
+ if existing is not None and existing.process.returncode is not None:
logger.info(
- "[ClaudeSessionPool] dropping dead session for "
- "memory_node=%s pid=%s",
- memory_node_id, existing.pty_handle.pid,
+ "[ClaudeSessionPool] dropping dead session "
+ "memory_node=%s pid=%s exit=%s — will respawn",
+ memory_node_id, existing.process.pid,
+ existing.process.returncode,
)
+ crashed_uuid = existing.current_session_uuid
await self._terminate_locked(memory_node_id, reason="crashed")
existing = None
if existing is not None:
- # Warm path. Take the per-session lock OUTSIDE the
- # pool_lock to avoid deadlocks if a turn is still
- # finishing.
- pass
- else:
- # Cold path. Evict LRU if at capacity.
- if len(self._pool) >= self._max_size:
- await self._evict_lru_locked()
- session = await self._spawn(
- memory_node_id=memory_node_id,
- spec=spec,
- cwd=cwd,
- env=env,
- defaults=defaults,
- mcp_endpoint_url=mcp_endpoint_url,
- mcp_bearer_token=mcp_bearer_token,
- connected_tool_names=connected_tool_names,
- )
- self._pool[memory_node_id] = session
+ existing.last_used_at = time.monotonic()
logger.info(
- "[ClaudeSessionPool] spawned new session memory_node=%s "
- "pid=%s uuid=%s",
- memory_node_id, session.pty_handle.pid,
- session.current_session_uuid,
+ "[ClaudeSessionPool] warm reuse memory_node=%s pid=%s uuid=%s",
+ memory_node_id, existing.process.pid,
+ existing.current_session_uuid or "(unresolved)",
)
- # Typed CloudEvent — FE wires per-memory-node lifecycle
- # status from the same envelope as agent_progress /
- # node_parameters_updated. Fire-and-forget; broadcaster
- # is the process-wide singleton.
- await self._emit_event(
- "spawned",
- memory_node_id=memory_node_id,
- workflow_id=workflow_id,
- session_uuid=session.current_session_uuid,
- pid=session.pty_handle.pid,
- )
- return session
-
- # Warm-reuse path. Returned as-is — preserves memory continuity
- # (claude appends to its existing JSONL on the next prompt). The
- # caller can opt in to context reset via the explicit
- # :meth:`clear` method.
- assert existing is not None
- existing.last_used_at = time.monotonic()
- logger.info(
- "[ClaudeSessionPool] warm reuse memory_node=%s pid=%s uuid=%s",
- memory_node_id, existing.pty_handle.pid,
- existing.current_session_uuid,
- )
- return existing
+ return existing
+
+ if len(self._pool) >= self._max_size:
+ await self._evict_lru_locked()
+
+ # When recovering from a crash, splice the captured UUID
+ # into the spec so the spawn emits ``--resume <UUID>``.
+ if crashed_uuid and not spec.resume_session_id:
+ spec.resume_session_id = crashed_uuid
+ spec.continue_session = False
+
+ session = await self._spawn(
+ memory_node_id=memory_node_id,
+ spec=spec,
+ cwd=cwd,
+ env=env,
+ defaults=defaults,
+ mcp_endpoint_url=mcp_endpoint_url,
+ mcp_bearer_token=mcp_bearer_token,
+ connected_tool_names=connected_tool_names,
+ )
+ if crashed_uuid:
+ # The new subprocess is resuming the prior session; pre-seed
+ # the UUID so the first turn's emitted CloudEvents carry
+ # the right id even before the result event lands.
+ session.current_session_uuid = crashed_uuid
+ self._pool[memory_node_id] = session
+ logger.info(
+ "[ClaudeSessionPool] spawned new session memory_node=%s pid=%s",
+ memory_node_id, session.process.pid,
+ )
+ await self._emit_event(
+ "spawned",
+ memory_node_id=memory_node_id,
+ workflow_id=workflow_id,
+ session_uuid=session.current_session_uuid,
+ pid=session.process.pid,
+ )
+ return session
async def clear(
self,
@@ -267,43 +285,44 @@ class ClaudeSessionPool:
*,
workflow_id: Optional[str] = None,
) -> str:
- """Explicit ``/clear`` — mints a new session UUID and rotates
- the watcher. Returns the new UUID. Use when the user wants to
- start a fresh conversation in the same pooled process (e.g.
- a "Clear conversation" button on simpleMemory). The memory
- bridge auto-picks up the new UUID via the next ``send_turn``
- result event."""
- old_uuid = session.current_session_uuid
- await self._clear_and_swap(session)
- if session.current_session_uuid != old_uuid:
+ """Kill the subprocess, drop the captured UUID. Next ``acquire``
+ spawns fresh with no continuity flag (claude assigns a new
+ session UUID).
+
+ Stream-json input mode has no in-process slash-command
+ equivalent of the TUI's ``/clear`` (the VSCode extension
+ source confirms this — context resets are subprocess restarts,
+ not slash messages). Emits ``claude.session.cleared`` for FE
+ parity with the old PTY-era contract.
+ """
+ async with session.lock:
+ old_uuid = session.current_session_uuid
+ # Drop the pool entry and kill the subprocess.
+ await self.terminate(session.memory_node_id)
+ if old_uuid:
await self._emit_event(
"cleared",
memory_node_id=session.memory_node_id,
workflow_id=workflow_id,
old_session_uuid=old_uuid,
- new_session_uuid=session.current_session_uuid,
+ new_session_uuid="",
)
- return session.current_session_uuid
+ return ""
- async def release(
- self, session: PooledClaudeSession,
- ) -> None:
- """Update last-used-at so the reaper measures idle time from now.
-
- Nothing else needed — the per-turn lock is released by
- ``send_turn``'s context manager, so once ``release`` returns the
- session is genuinely idle and the reaper may evict it.
- """
+ async def release(self, session: PooledClaudeSession) -> None:
+ """Update ``last_used_at`` so the reaper measures from now."""
session.last_used_at = time.monotonic()
async def terminate(self, memory_node_id: str) -> None:
- """Force-terminate a specific pooled session."""
+ """Force-drop a specific pooled session."""
async with self._pool_lock:
await self._terminate_locked(memory_node_id)
async def shutdown_all(self) -> None:
- """Terminate every pooled session + stop the reaper. Wire into
- FastAPI's lifespan ``shutdown`` event."""
+ """Terminate every pooled subprocess + stop the reaper.
+
+ Wire into FastAPI's lifespan ``shutdown`` event.
+ """
self._shutdown.set()
if self._reaper_task is not None and not self._reaper_task.done():
self._reaper_task.cancel()
@@ -312,7 +331,6 @@ class ClaudeSessionPool:
except (asyncio.CancelledError, Exception):
pass
self._reaper_task = None
-
async with self._pool_lock:
keys = list(self._pool.keys())
for key in keys:
@@ -326,18 +344,53 @@ class ClaudeSessionPool:
timeout_seconds: int = 600,
workflow_id: Optional[str] = None,
) -> SessionResult:
- """Write a prompt to a pooled session and await the next
- ``result`` event. Serialises against other callers via the
- session's lock. Emits a ``claude.session.usage`` CloudEvent
- after each successful turn so the FE can render cost/token
- data per memory node."""
+ """Write one stream-json user message to ``proc.stdin`` and await
+ the next ``result`` event from claude's stdout stream.
+
+ The stdout reader task (started at spawn time) parses each line
+ as a stream-json event and dispatches via
+ :meth:`_handle_stream_event`. When the final ``result`` event
+ lands, ``result_event`` is set and we return.
+
+ Serialised by ``session.lock`` so two concurrent ``send_turn``
+ calls can't interleave their stream-json lines on stdin.
+ """
async with session.lock:
+ if session.process.returncode is not None:
+ return self._build_result_from_events(
+ session=session,
+ events=[],
+ prompt=prompt,
+ success=False,
+ error=(
+ f"claude subprocess exited (code "
+ f"{session.process.returncode}) before turn"
+ ),
+ )
+
session.result_event.clear()
session.events_this_turn = []
- # Claude's interactive TUI reads input on Enter (``\r``);
- # closing stdin does NOT submit (claude-code#15553).
- payload = (prompt.rstrip("\r\n") + "\r").encode("utf-8")
- await session.pty_handle.write(payload)
+
+ # Stream-json input shape — the VSCode extension's wire
+ # format. Newline-delimited; one JSON object per turn.
+ message = {
+ "type": "user",
+ "message": {"role": "user", "content": prompt},
+ }
+ payload = (json.dumps(message) + "\n").encode("utf-8")
+ try:
+ assert session.process.stdin is not None
+ session.process.stdin.write(payload)
+ await session.process.stdin.drain()
+ except (ConnectionError, BrokenPipeError, AttributeError) as exc:
+ return self._build_result_from_events(
+ session=session,
+ events=[],
+ prompt=prompt,
+ success=False,
+ error=f"failed to deliver prompt to claude stdin: {exc}",
+ )
+
try:
await asyncio.wait_for(
session.result_event.wait(),
@@ -351,19 +404,24 @@ class ClaudeSessionPool:
)
return self._build_result_from_events(
session=session,
+ events=session.events_this_turn,
prompt=prompt,
success=False,
error=f"timeout after {timeout_seconds}s",
)
+
session.last_used_at = time.monotonic()
result = self._build_result_from_events(
session=session,
+ events=session.events_this_turn,
prompt=prompt,
success=True,
)
- # Surface per-turn usage as a typed CloudEvent. Same data
- # ``/usage`` displays in the TUI — but structured, so the FE
- # can render a panel without scraping plain-text TUI output.
+ # Persist the authoritative UUID from the result event so
+ # crash-recovery respawns can emit ``--resume <UUID>``.
+ if result.session_id:
+ session.current_session_uuid = result.session_id
+
cu = result.canonical_usage
await self._emit_event(
"usage",
@@ -381,7 +439,7 @@ class ClaudeSessionPool:
return result
# ------------------------------------------------------------------
- # Spawn / clear / dispatch internals
+ # Spawn internals
# ------------------------------------------------------------------
async def _spawn(
@@ -396,24 +454,11 @@ class ClaudeSessionPool:
mcp_bearer_token: Optional[str],
connected_tool_names: Optional[List[str]],
) -> PooledClaudeSession:
- """Cold-spawn a new pooled claude session. Caller holds pool_lock."""
- from services.claude_oauth import MACHINA_CLAUDE_DIR
- from .session import _PROJECT_KEY_RE # noqa: PLC0415 — internal reuse
-
- # Where claude will write JSONLs for this cwd.
- project_key = _PROJECT_KEY_RE.sub("-", str(cwd))
- project_dir = Path(MACHINA_CLAUDE_DIR) / "projects" / project_key
- try:
- project_dir.mkdir(parents=True, exist_ok=True)
- except OSError as exc:
- logger.warning(
- "[ClaudeSessionPool] mkdir project_dir failed dir=%s exc=%s",
- project_dir, exc,
- )
-
- # Build argv WITHOUT the prompt — we'll write the first turn's
- # prompt to the PTY in `send_turn` so the spawn-to-ready path
- # is the same as the post-/clear path.
+ """Cold-spawn a new pooled claude subprocess. Caller holds pool_lock."""
+ # ``include_prompt`` is ignored by the new ``interactive_argv``
+ # (stream-json input mode reads the prompt from stdin), but we
+ # pass ``False`` to make the intent explicit for any future
+ # provider that still honours it.
argv = self._provider.interactive_argv(
spec,
defaults=defaults,
@@ -423,81 +468,124 @@ class ClaudeSessionPool:
include_prompt=False,
)
- # Spawn via the cross-platform PTY transport.
- transport = get_pty_transport()
- spawn_time = time.monotonic()
- pty_handle = await transport.spawn(argv, cwd=cwd, env=env)
-
- # Locate the JSONL claude is using. Works uniformly for fresh
- # spawns (new file appears) and ``--continue`` spawns (existing
- # file's mtime updates as claude appends a system/init event).
- jsonl_path = await self._wait_for_session_jsonl(
- project_dir, spawn_time,
+ # Subprocess spawn — the VSCode-extension pattern. PIPE on
+ # stdin/stdout/stderr; no PTY. The stdout-reader task below
+ # parses each stream-json line into an event and dispatches it.
+ process = await asyncio.create_subprocess_exec(
+ *argv,
+ cwd=str(cwd),
+ env=env,
+ stdin=asyncio.subprocess.PIPE,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
)
- session_uuid = session_uuid_from_jsonl_path(jsonl_path) or ""
-
- # Build the session shell with placeholder watchers, then start
- # them. Order: dir_watcher first so any subsequent /clear
- # detects the post-clear file via the dir baseline. The bearer
- # token is stored on the session so warm reuse can re-register
- # the batch context with the SAME token the claude already has
- # in its argv (the caller owns issue / unregister).
+
session = PooledClaudeSession(
memory_node_id=memory_node_id,
- project_dir=project_dir,
- pty_handle=pty_handle,
- current_session_uuid=session_uuid,
- current_jsonl_path=jsonl_path,
- dir_watcher=None, # type: ignore[arg-type]
- jsonl_watcher=None, # type: ignore[arg-type]
+ process=process,
cwd=cwd,
- bearer_token=mcp_bearer_token or "",
)
- async def _on_new_jsonl(path: Path) -> None:
- session.new_jsonl_path = path
- session.new_jsonl_event.set()
+ # stdout reader — the single runtime contract in stream-json
+ # output mode. Each line is one stream-json event
+ # (``system/init``, ``assistant``, ``user``, ``result``,
+ # ``system/compact_boundary``, etc.). We dispatch via
+ # :meth:`_handle_stream_event` which populates the per-turn
+ # buffer and signals ``result_event`` on the final event.
+ async def _consume_stdout() -> None:
+ assert process.stdout is not None
+ try:
+ while True:
+ raw = await process.stdout.readline()
+ if not raw:
+ return
+ line = raw.decode("utf-8", errors="replace").strip()
+ if not line:
+ continue
+ try:
+ event = json.loads(line)
+ except json.JSONDecodeError:
+ logger.debug(
+ "[ClaudeSessionPool] stdout non-JSON line "
+ "memory_node=%s line=%r",
+ memory_node_id, line[:200],
+ )
+ continue
+ try:
+ await self._handle_stream_event(session, event)
+ except Exception as exc: # pragma: no cover
+ logger.warning(
+ "[ClaudeSessionPool] handler raised "
+ "memory_node=%s exc=%s",
+ memory_node_id, exc,
+ )
+ except (asyncio.CancelledError, ConnectionError):
+ return
+ except Exception as exc: # pragma: no cover — defensive
+ logger.debug(
+ "[ClaudeSessionPool] stdout reader memory_node=%s exc=%s",
+ memory_node_id, exc,
+ )
- def _make_event_handler(s: PooledClaudeSession):
- async def _on_event(event: Dict[str, Any]) -> None:
- await self._handle_jsonl_event(s, event)
- return _on_event
+ async def _drain_stderr() -> None:
+ assert process.stderr is not None
+ try:
+ while True:
+ raw = await process.stderr.readline()
+ if not raw:
+ return
+ line = raw.decode("utf-8", errors="replace").rstrip()
+ if line:
+ logger.warning(
+ "[ClaudeSessionPool] claude stderr "
+ "memory_node=%s pid=%s: %s",
+ memory_node_id, process.pid, line,
+ )
+ except (asyncio.CancelledError, ConnectionError):
+ return
+ except Exception as exc: # pragma: no cover — defensive
+ logger.debug(
+ "[ClaudeSessionPool] stderr drain memory_node=%s exc=%s",
+ memory_node_id, exc,
+ )
- session.dir_watcher = JsonlDirWatcher(
- project_dir, on_new_file=_on_new_jsonl,
+ session.stdout_reader_task = asyncio.create_task(
+ _consume_stdout(),
+ name=f"ClaudeSessionPool.stdout_reader({memory_node_id})",
)
- await session.dir_watcher.start()
- session.jsonl_watcher = JsonlWatcher(
- jsonl_path,
- on_event=_make_event_handler(session),
- start_from_end=False,
+ session.stderr_drain_task = asyncio.create_task(
+ _drain_stderr(),
+ name=f"ClaudeSessionPool.stderr_drain({memory_node_id})",
)
- await session.jsonl_watcher.start()
return session
- async def _handle_jsonl_event(
+ # ------------------------------------------------------------------
+ # Stream-json event dispatch
+ # ------------------------------------------------------------------
+
+ async def _handle_stream_event(
self, session: PooledClaudeSession, event: Dict[str, Any],
) -> None:
- """Shared JSONL event dispatcher for both spawn-time and
- post-``/clear`` watchers.
+ """Per-event dispatcher for stream-json lines on ``proc.stdout``.
Three concerns:
- 1. Append to ``session.events_this_turn`` so :meth:`send_turn`
- can build a :class:`SessionResult` from the turn's events.
- 2. Set ``session.result_event`` when the provider's final
- event arrives (``type == "result"``).
- 3. Detect native compaction (``type=="system"``,
- ``subtype=="compact_boundary"``) and forward to
- :class:`CompactionService` so the existing token-tracking
- pipeline accounts for it — avoids double-compaction
- (client-side summarisation + native auto-compaction
- running independently).
+ 1. Capture the session UUID from any event that carries one
+ (``system/init`` for fresh spawns, ``result`` for the
+ authoritative value) so crash-recovery respawns can emit
+ ``--resume <UUID>``.
+ 2. Append to the per-turn buffer + signal ``result_event``
+ on the final ``result`` event so ``send_turn`` returns.
+ 3. Forward ``system/compact_boundary`` events to
+ :class:`CompactionService` so the local-threshold path
+ doesn't double-fire on claude's native auto-compaction.
"""
+ sid = event.get("session_id") or event.get("sessionId")
+ if sid and not session.current_session_uuid:
+ session.current_session_uuid = sid
session.events_this_turn.append(event)
if self._provider.is_final_event(event):
session.result_event.set()
-
if (
event.get("type") == "system"
and event.get("subtype") == "compact_boundary"
@@ -508,38 +596,24 @@ class ClaudeSessionPool:
async def _record_native_compaction(
session: PooledClaudeSession, event: Dict[str, Any],
) -> None:
- """Forward a ``system/compact_boundary`` event to the existing
- :class:`CompactionService` so its token-state machine reflects
- the native compaction that just happened.
-
- Without this, the local-threshold path in
- ``services/ai.py:_track_token_usage`` and claude's own
- auto-compaction would both trigger summarisations and the UI's
- token gauge would race against claude's internal state.
- """
+ """Forward a ``system/compact_boundary`` event to
+ :class:`CompactionService` so the local-threshold path doesn't
+ double-fire on claude's native auto-compaction."""
try:
from services.compaction import get_compaction_service
- except Exception: # pragma: no cover — defensive
+ except Exception: # pragma: no cover
return
-
svc = get_compaction_service()
- if svc is None: # not initialised in test envs
+ if svc is None:
return
-
metadata = event.get("compact_metadata") or {}
pre_tokens = int(metadata.get("pre_tokens") or 0)
- # `tokens_after` after native compaction isn't directly visible
- # in the JSONL — claude doesn't emit a "post-summary token
- # count" event. The next `result` event's `usage` block will
- # carry the true post-compaction cumulative; recording 0 here
- # is a conservative reset that lets the next turn's `track()`
- # call set the accurate cumulative.
try:
await svc.record(
session_id=session.memory_node_id,
node_id=session.memory_node_id,
provider="claude",
- model="", # claude doesn't emit the model on this event
+ model="",
tokens_before=pre_tokens,
tokens_after=0,
summary=None,
@@ -550,132 +624,23 @@ class ClaudeSessionPool:
session.memory_node_id, pre_tokens,
metadata.get("trigger", "unknown"),
)
- except Exception as exc: # pragma: no cover — best-effort
+ except Exception as exc: # pragma: no cover
logger.debug(
"[ClaudeSessionPool] compaction.record failed: %s", exc,
)
- async def _clear_and_swap(self, session: PooledClaudeSession) -> None:
- """Send ``/clear``, await the new JSONL filename via the dir
- watcher, swap the file watcher to the new path. Holds the
- per-session lock so concurrent turns don't race."""
- async with session.lock:
- session.new_jsonl_event.clear()
- session.new_jsonl_path = None
- # Stop the current file watcher BEFORE sending /clear so
- # any tail-end output of the old session doesn't leak into
- # the new turn's events buffer.
- await session.jsonl_watcher.stop()
- session.events_this_turn = []
- session.result_event.clear()
-
- # Slash commands must be at the start of a line; claude
- # auto-fires on Enter.
- await session.pty_handle.write(b"/clear\r")
-
- try:
- await asyncio.wait_for(
- session.new_jsonl_event.wait(),
- timeout=_CLEAR_JSONL_TIMEOUT,
- )
- except asyncio.TimeoutError:
- logger.warning(
- "[ClaudeSessionPool] /clear didn't produce a new JSONL "
- "memory_node=%s within %ss; falling back to mtime sort",
- session.memory_node_id, _CLEAR_JSONL_TIMEOUT,
- )
-
- new_path = session.new_jsonl_path
- if new_path is None:
- # Fallback: pick the newest .jsonl in the project dir.
- try:
- candidates = [
- p for p in session.project_dir.iterdir()
- if p.suffix == ".jsonl"
- ]
- if candidates:
- new_path = max(candidates, key=lambda p: p.stat().st_mtime)
- except OSError:
- pass
-
- if new_path is not None and new_path != session.current_jsonl_path:
- session.current_jsonl_path = new_path
- session.current_session_uuid = (
- session_uuid_from_jsonl_path(new_path) or ""
- )
- logger.info(
- "[ClaudeSessionPool] /clear rotated memory_node=%s "
- "new_uuid=%s",
- session.memory_node_id, session.current_session_uuid,
- )
-
- # Reattach the file watcher to whatever path we believe is
- # current. If detection failed we re-watch the previous
- # file — the next turn's `result` event will still fire.
- # Reuses :meth:`_handle_jsonl_event` so the compaction +
- # result-event detection are identical to the spawn path.
- async def _on_event(event: Dict[str, Any]) -> None:
- await self._handle_jsonl_event(session, event)
-
- session.jsonl_watcher = JsonlWatcher(
- session.current_jsonl_path,
- on_event=_on_event,
- start_from_end=False,
- )
- await session.jsonl_watcher.start()
-
- async def _wait_for_session_jsonl(
- self, project_dir: Path, spawn_time: float,
- ) -> Path:
- """Find the JSONL claude is using post-spawn via mtime.
-
- Works for both fresh-spawn (claude creates a new file) and
- ``--continue`` (claude appends an init event to the most
- recent existing file, updating its mtime). Picks the newest
- ``.jsonl`` whose mtime is at least ``spawn_time - 1s`` (grace
- for clock skew + filesystem mtime resolution).
- """
- deadline = spawn_time + _CLEAR_JSONL_TIMEOUT
- mtime_floor = spawn_time - 1.0
- while time.monotonic() < deadline:
- try:
- jsonls = [
- p for p in project_dir.iterdir()
- if p.suffix == ".jsonl"
- ]
- except OSError:
- jsonls = []
- if jsonls:
- try:
- newest = max(jsonls, key=lambda p: p.stat().st_mtime)
- if newest.stat().st_mtime >= mtime_floor:
- return newest
- except OSError:
- pass
- await asyncio.sleep(0.1)
- raise TimeoutError(
- f"No session JSONL touched under {project_dir} within "
- f"{_CLEAR_JSONL_TIMEOUT}s"
- )
-
def _build_result_from_events(
self,
*,
session: PooledClaudeSession,
+ events: List[Dict[str, Any]],
prompt: str,
success: bool,
error: Optional[str] = None,
) -> SessionResult:
- """Translate the per-turn event buffer to a ``SessionResult``.
-
- Reuses the provider's ``event_to_session_result`` so the cost
- / token / response extraction stays identical to the non-
- pooled path.
- """
+ """Translate per-turn JSONL events to a :class:`SessionResult`."""
provider_result = self._provider.event_to_session_result(
- session.events_this_turn,
- stderr="",
- exit_code=0 if success else -1,
+ events, stderr="", exit_code=0 if success else -1,
)
final_success = success and provider_result.get("success", True)
final_error = error or provider_result.get("error")
@@ -693,14 +658,14 @@ class ClaudeSessionPool:
tool_calls=int(provider_result.get("tool_calls", 0)),
canonical_usage=provider_result.get(
"canonical_usage",
- ) or self._provider.canonical_usage(session.events_this_turn),
+ ) or self._provider.canonical_usage(events),
provider_data=dict(provider_result.get("provider_data") or {}),
success=final_success,
error=final_error if not final_success else None,
)
# ------------------------------------------------------------------
- # Eviction / reaper
+ # Termination + eviction
# ------------------------------------------------------------------
async def _terminate_locked(
@@ -709,35 +674,55 @@ class ClaudeSessionPool:
*,
reason: str = "explicit",
) -> None:
- """Caller holds ``self._pool_lock``. ``reason`` is the
- CloudEvent ``reason`` value (``idle`` / ``crashed`` / ``evicted``
- / ``shutdown`` / ``explicit``) — drives the
- ``claude.session.terminated`` envelope."""
+ """Caller holds ``self._pool_lock``. Stop the watcher, close
+ stdin (graceful exit), wait briefly, then kill if still alive.
+ Emits the ``claude.session.terminated`` CloudEvent."""
session = self._pool.pop(memory_node_id, None)
if session is None:
return
session_uuid = session.current_session_uuid
- try:
- await session.jsonl_watcher.stop()
- except Exception as exc: # pragma: no cover — defensive
- logger.debug(
- "[ClaudeSessionPool] watcher stop on terminate: %s", exc,
- )
- try:
- await session.dir_watcher.stop()
- except Exception as exc: # pragma: no cover
- logger.debug(
- "[ClaudeSessionPool] dir watcher stop on terminate: %s", exc,
- )
- try:
- await session.pty_handle.kill()
- except Exception as exc: # pragma: no cover
- logger.debug(
- "[ClaudeSessionPool] PTY kill on terminate: %s", exc,
- )
+
+ # 1. Close stdin so claude can exit gracefully.
+ process = session.process
+ if process.returncode is None and process.stdin is not None:
+ try:
+ process.stdin.close()
+ except (ConnectionError, BrokenPipeError, AttributeError):
+ pass
+
+ # 2. Brief grace period for graceful exit.
+ if process.returncode is None:
+ try:
+ await asyncio.wait_for(process.wait(), timeout=_SHUTDOWN_GRACE)
+ except asyncio.TimeoutError:
+ pass
+
+ # 3. Escalate to kill if still alive.
+ if process.returncode is None:
+ try:
+ process.kill()
+ await process.wait()
+ except ProcessLookupError:
+ pass
+ except Exception as exc: # pragma: no cover
+ logger.debug(
+ "[ClaudeSessionPool] kill memory_node=%s exc=%s",
+ memory_node_id, exc,
+ )
+
+ # 4. Cancel reader/drain tasks (they'll exit on their own when
+ # the pipes close, but cancel makes the cleanup deterministic).
+ for task in (session.stdout_reader_task, session.stderr_drain_task):
+ if task is not None and not task.done():
+ task.cancel()
+ try:
+ await task
+ except (asyncio.CancelledError, Exception):
+ pass
+
logger.info(
- "[ClaudeSessionPool] terminated memory_node=%s reason=%s",
- memory_node_id, reason,
+ "[ClaudeSessionPool] terminated memory_node=%s pid=%s reason=%s",
+ memory_node_id, process.pid, reason,
)
await self._emit_event(
"terminated",
@@ -754,8 +739,6 @@ class ClaudeSessionPool:
if not sess.lock.locked()
]
if not idle_entries:
- # All sessions in-flight; nothing safe to evict. Caller
- # spawns over the soft cap.
logger.info(
"[ClaudeSessionPool] all %d entries in-flight; pool over cap",
len(self._pool),
@@ -770,7 +753,7 @@ class ClaudeSessionPool:
await self._terminate_locked(oldest_key, reason="evicted")
# ------------------------------------------------------------------
- # CloudEvent emission helper
+ # CloudEvent emission helper (unchanged)
# ------------------------------------------------------------------
async def _emit_event(
@@ -783,16 +766,15 @@ class ClaudeSessionPool:
) -> None:
"""Dispatch one of the four claude-session CloudEvents.
- Lazy-imports the broadcaster singleton so the pool stays a
- leaf service. Failures are swallowed (best-effort) — a missed
- UI update must not break the agent loop.
+ Lazy-imports the broadcaster singleton so the pool stays a leaf
+ service. Best-effort: a missed UI update must not break the
+ agent loop.
"""
try:
from services.status_broadcaster import get_status_broadcaster
broadcaster = get_status_broadcaster()
- except Exception: # pragma: no cover — defensive
+ except Exception: # pragma: no cover
return
-
try:
if kind == "spawned":
await broadcaster.broadcast_claude_session_spawned(
@@ -832,10 +814,9 @@ class ClaudeSessionPool:
num_turns=payload.get("num_turns"),
workflow_id=workflow_id,
)
- except Exception as exc: # pragma: no cover — best-effort
+ except Exception as exc: # pragma: no cover
logger.debug(
- "[ClaudeSessionPool] _emit_event(%s) failed: %s",
- kind, exc,
+ "[ClaudeSessionPool] _emit_event(%s) failed: %s", kind, exc,
)
async def _reaper_loop(self) -> None:
@@ -846,14 +827,11 @@ class ClaudeSessionPool:
self._shutdown.wait(),
timeout=self._reaper_interval,
)
- return # shutdown fired
+ return
except asyncio.TimeoutError:
pass
-
now = time.monotonic()
async with self._pool_lock:
- # Skip in-flight sessions — a turn that takes longer
- # than idle_ttl would otherwise get reaped mid-flight.
expired_keys = [
key for key, sess in self._pool.items()
if not sess.lock.locked()
diff --git a/server/tests/conftest.py b/server/tests/conftest.py
index 5f925c64..6ad46a55 100644
--- a/server/tests/conftest.py
+++ b/server/tests/conftest.py
@@ -56,6 +56,28 @@ def _stub_log_execution_time(*_args, **_kwargs):
# real submodule attributes so imports resolve without touching the real
# heavy deps (dependency_injector, cryptography, ...).
_core_pkg = _make_package("core")
+def _stub_log_context(**_fields):
+ """Stub for ``core.logging.log_context`` (async ctx manager) and
+ ``log_context_sync``. Both are no-ops under test."""
+ from contextlib import asynccontextmanager, contextmanager
+
+ @asynccontextmanager
+ async def _async_cm():
+ yield
+
+ return _async_cm()
+
+
+def _stub_log_context_sync(**_fields):
+ from contextlib import contextmanager
+
+ @contextmanager
+ def _sync_cm():
+ yield
+
+ return _sync_cm()
+
+
_make_submodule(
"core",
"logging",
@@ -63,6 +85,8 @@ _make_submodule(
"get_logger": MagicMock(return_value=MagicMock()),
"log_execution_time": _stub_log_execution_time,
"log_api_call": MagicMock(),
+ "log_context": _stub_log_context,
+ "log_context_sync": _stub_log_context_sync,
},
)
_make_submodule("core", "container", {"container": MagicMock()})
diff --git a/server/tests/services/cli_agent/test_providers.py b/server/tests/services/cli_agent/test_providers.py
index 90a04dc1..f7a8fd59 100644
--- a/server/tests/services/cli_agent/test_providers.py
+++ b/server/tests/services/cli_agent/test_providers.py
@@ -74,33 +74,41 @@ class TestClaudeArgv:
def test_minimum_required_flags(self, claude_provider):
task = ClaudeTaskSpec(prompt="hello world")
argv = claude_provider.interactive_argv(task, defaults={})
- # Prompt is the positional after `--` (interactive mode). No
- # `-p` / `--print` / `--output-format stream-json` anymore.
+ # VSCode-extension pattern (stream-json over stdio pipes, no PTY).
+ # ``-p`` / ``--print`` are NEVER emitted — we stay in interactive
+ # billing (entrypoint ``claude-vscode``, not ``sdk-cli``).
assert "-p" not in argv
assert "--print" not in argv
- assert "--output-format" not in argv
- assert "--verbose" not in argv
- assert "--include-partial-messages" not in argv
- assert "--include-hook-events" not in argv
- assert "--" in argv
- assert "hello world" in argv
- # Ordering: `--` immediately precedes the prompt.
- sep_idx = argv.index("--")
- assert argv[sep_idx + 1] == "hello world"
+ # Stream-json I/O flags ARE emitted now (replace the headless
+ # PTY pattern):
+ assert "--output-format" in argv
+ out_idx = argv.index("--output-format")
+ assert argv[out_idx + 1] == "stream-json"
+ assert "--input-format" in argv
+ in_idx = argv.index("--input-format")
+ assert argv[in_idx + 1] == "stream-json"
+ assert "--verbose" in argv # required for stream-json detail
+ assert "--ide" in argv # lockfile auto-discovery
+ # The prompt is NEVER a positional in stream-json mode — it goes
+ # over ``proc.stdin``. ``--`` separator is gone.
+ assert "--" not in argv
+ assert "hello world" not in argv
# Defaults applied
assert "--model" in argv
assert "claude-sonnet-4-6" in argv # default_model from JSON
- # `-p`-only flags no longer emitted
+ # ``-p``-only flags still not emitted (kept on the spec for back-compat)
assert "--max-turns" not in argv
assert "--max-budget-usd" not in argv
assert "--fallback-model" not in argv
# Tool + permission machinery preserved
assert "--allowedTools" in argv
assert "--permission-mode" in argv
- # `bypassPermissions` is the documented mode for non-interactive
- # automation (https://code.claude.com/docs/en/permission-modes).
+ # Default permission mode is read from ``config/ai_cli_providers.json``
+ # (currently ``acceptEdits``). Callers wanting ``bypassPermissions``
+ # set it explicitly on ``task.permission_mode`` or via the per-call
+ # ``defaults`` arg.
perm_idx = argv.index("--permission-mode")
- assert argv[perm_idx + 1] == "bypassPermissions"
+ assert argv[perm_idx + 1] == "acceptEdits"
def test_no_session_id_flag_in_interactive(self, claude_provider):
"""Claude assigns its own session UUID in interactive mode; we
@@ -162,17 +170,24 @@ class TestClaudeArgv:
assert "--append-system-prompt" in argv
assert "be concise" in argv
- def test_include_prompt_false_omits_positional(self, claude_provider):
- """The session pool uses `include_prompt=False` when spawning a
- process whose first prompt will be written to the PTY (e.g.
- after a `/clear`). The argv carries no positional prompt and
- therefore no `--` separator."""
- task = ClaudeTaskSpec(prompt="will-be-piped-to-pty")
- argv = claude_provider.interactive_argv(
+ def test_include_prompt_is_ignored_in_stream_json_mode(self, claude_provider):
+ """``include_prompt`` is kept on the signature for back-compat
+ but is intentionally ignored in stream-json input mode — passing
+ ``-- "<prompt>"`` would double-send the first turn (once via
+ argv, once via stdin). Both ``True`` and ``False`` produce the
+ same argv shape: no ``--`` separator, no positional prompt."""
+ task = ClaudeTaskSpec(prompt="will-be-piped-via-stdin")
+ argv_true = claude_provider.interactive_argv(
+ task, defaults={}, include_prompt=True,
+ )
+ argv_false = claude_provider.interactive_argv(
task, defaults={}, include_prompt=False,
)
- assert "--" not in argv
- assert "will-be-piped-to-pty" not in argv
+ for argv in (argv_true, argv_false):
+ assert "--" not in argv
+ assert "will-be-piped-via-stdin" not in argv
+ # Same shape regardless of the back-compat flag.
+ assert argv_true == argv_false
def test_wrong_task_type_raises(self, claude_provider):
codex_task = CodexTaskSpec(prompt="x")