Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(cli_agent): reflect --continue cutover + mtime-based JSONL discovery
trohitg8c6ed2ebf2f5
diff --git a/CLAUDE.md b/CLAUDE.mdindex 0fe7d829..1d3e81e0 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -47,7 +47,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[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. `ClaudeSessionPool` keyed by `simpleMemory.node_id` reuses warm processes across batches (non-disruptive — preserves memory continuity). 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). |+| **[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 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. |diff --git a/docs-internal/claude_code_interactive_mode.md b/docs-internal/claude_code_interactive_mode.mdindex f706e249..4b9d4572 100644--- a/docs-internal/claude_code_interactive_mode.md+++ b/docs-internal/claude_code_interactive_mode.md@@ -27,8 +27,9 @@ 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 argvflags we care about — `--mcp-config`, `--strict-mcp-config`,`--allowedTools`, `--permission-mode`, `--append-system-prompt`,-`--resume`, `--model`, `--effort`, `--add-dir`, `--disallowedTools`,-`--agent` — all work in interactive mode.+`--resume`, **`--continue`** (new primary continuity flag — see+"Memory bridge" below), `--model`, `--effort`, `--add-dir`,+`--disallowedTools`, `--agent` — all work in interactive mode.## What we dropped@@ -58,7 +59,7 @@ Two orthogonal layers:| **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 |-| **Resume across spawns** | `claude --resume <UUID>` | 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 terminalsand Spyder's IPython console) so the historical reason to route Windows@@ -95,9 +96,11 @@ memory node reuse the same warm `claude` PTY:JSONL so the conversation continues. This is the load-bearinginvariant for `simpleMemory` continuity.- **Acquire (cold)** — spawn fresh via `PtyTransport`, locate the- newly-created JSONL by mtime, 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.+ 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, awaitsthe new JSONL filename via the persistent `JsonlDirWatcher`, swapsthe file watcher. Per@@ -196,25 +199,50 @@ interactive dialogs, kill the session, or open a browser):`/config`, `/install-github-app`, `/install-slack-app`, `/teleport`,`/heapdump`.-## Memory bridge — unchanged+## Memory bridge — `--continue`, not UUID round-trip-The `simpleMemory.last_session_id` ↔ `--resume <UUID>` contract works-identically in interactive mode because the on-disk JSONL is the-same format. The invariants:+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: claude assigns its own UUID; the pool / `AICliSession`- discovers it via the new JSONL filename, saves it to- `simpleMemory.last_session_id`.-- Subsequent runs (non-pooled): argv `--resume <last_session_id>`.-- Subsequent runs (pooled, warm): no respawn — the warm PTY continues- in its current UUID.-- Subsequent runs (pooled, after `pool.clear`): a new UUID is captured- on the next `result` event and persisted.-- Auto-clear-stale: if claude reports `No conversation found with- session ID: <UUID>`, `_persist_memory` wipes the broken- `last_session_id` so the next run falls into the first-run branch.+- 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)