Skip to content

Self-improving AI Employees for everyone

feat(cli_agent): interactive PTY + on-disk JSONL replaces `-p` headless (Steps 1-4)

trohitg05905eff1a98
diff --git a/server/pyproject.toml b/server/pyproject.toml
index c4570777..12ca569c 100644
--- a/server/pyproject.toml
+++ b/server/pyproject.toml
@@ -122,6 +122,16 @@ dependencies = [
# to discover and call MachinaOs tools (mcp__machina__*) the same way
# VSCode's Claude Code extension does.
"mcp>=1.0.0",
+
+ # PTY transports — drive `claude` interactive TUI cross-platform.
+ # POSIX uses ptyprocess (wraps forkpty) for `loop.add_reader`-friendly
+ # async; Windows uses pywinpty v3.x which is Rust-backed via PyO3 +
+ # winpty-rs + Maturin (used by Jupyter Lab terminals and Spyder's
+ # IPython console). See docs-internal/claude_code_interactive_mode.md
+ # for the topology rationale and the deferred upgrade path to an
+ # out-of-process pty-host (VSCode's pattern).
+ "ptyprocess>=0.7.0; sys_platform != 'win32'",
+ "pywinpty>=3.0.3; sys_platform == 'win32'",
]
[project.optional-dependencies]
diff --git a/server/services/cli_agent/jsonl_watcher.py b/server/services/cli_agent/jsonl_watcher.py
new file mode 100644
index 00000000..c0962884
--- /dev/null
+++ b/server/services/cli_agent/jsonl_watcher.py
@@ -0,0 +1,337 @@
+"""On-disk JSONL watchers — protocol surface for interactive-mode claude.
+
+Claude writes its session transcript to
+``<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_uuid>.jsonl`` —
+same shape ``-p`` used to write to stdout (Claude Code CHANGELOG
+2.1.101 / 2.1.126 confirms the shared writer). In interactive mode we
+keep the TUI alive in a PTY and read events off disk; this module
+provides the two watchers ``AICliSession`` + ``ClaudeSessionPool`` need:
+
+ - :class:`JsonlWatcher` tails one specific JSONL file and dispatches
+ each new line as a parsed event. Drop-in replacement for the old
+ ``_consume_stdout`` NDJSON parser.
+
+ - :class:`JsonlDirWatcher` watches a directory for *new* JSONL files
+ appearing — the mechanism the session pool uses to capture the
+ new session UUID after sending ``/clear`` (which mints a fresh
+ UUID, not an in-place clear; see issue `claude-code#32871
+ <https://github.com/anthropics/claude-code/issues/32871>`_).
+
+Both use a simple poll loop (default 100 ms / 250 ms) rather than
+``watchdog``'s OS-native APIs (inotify/FSEvents/ReadDirectoryChangesW).
+Polling is good enough for our latency target (UI updates were already
+at the same cadence under the old stdout path), more predictable
+under high-frequency append, and avoids the well-known watchdog races
+on Windows under rapid file creation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, Optional, Set
+
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+EventHandler = Callable[[Dict[str, Any]], Awaitable[None]]
+"""Async callback fired once per parsed JSONL line."""
+
+FileHandler = Callable[[Path], Awaitable[None]]
+"""Async callback fired once per newly-detected .jsonl file."""
+
+
+class JsonlWatcher:
+ """Tail a specific JSONL file and dispatch new lines as events.
+
+ Replaces the old NDJSON-on-stdout consumer. Once :meth:`start` is
+ called, every newline-terminated chunk appended to ``path`` is read,
+ parsed with :func:`json.loads`, and handed to ``on_event``. Garbage
+ (unparseable lines, partial writes during an append) is silently
+ dropped — matches the old ``AnthropicClaudeProvider.parse_event``
+ return-None-on-error semantics.
+
+ The watcher is cancellation-safe: :meth:`stop` cancels the
+ background task and closes the open file handle. Calling
+ :meth:`stop` on an already-stopped watcher is a no-op.
+
+ Initial position: by default we seek to the END of the file at
+ :meth:`start` so we only see new appends. Pass ``start_from_end=False``
+ to replay the entire file (useful for picking up the result event
+ of a turn that completed while we were spawning).
+ """
+
+ __slots__ = (
+ "_path", "_on_event", "_poll_interval", "_start_from_end",
+ "_task", "_stopped",
+ )
+
+ def __init__(
+ self,
+ path: Path,
+ on_event: EventHandler,
+ *,
+ poll_interval: float = 0.1,
+ start_from_end: bool = False,
+ ) -> None:
+ self._path = Path(path)
+ self._on_event = on_event
+ self._poll_interval = max(0.01, float(poll_interval))
+ self._start_from_end = bool(start_from_end)
+ self._task: Optional[asyncio.Task[None]] = None
+ self._stopped = asyncio.Event()
+
+ @property
+ def path(self) -> Path:
+ return self._path
+
+ async def start(self) -> None:
+ """Spawn the tail-f task. Returns immediately."""
+ if self._task is not None and not self._task.done():
+ return # idempotent
+ self._stopped.clear()
+ self._task = asyncio.create_task(
+ self._run(),
+ name=f"JsonlWatcher({self._path.name})",
+ )
+
+ async def stop(self) -> None:
+ """Cancel the tail-f task and wait for it to settle."""
+ self._stopped.set()
+ if self._task is None:
+ return
+ if not self._task.done():
+ self._task.cancel()
+ try:
+ await self._task
+ except asyncio.CancelledError:
+ pass
+ except Exception as exc: # pragma: no cover — defensive
+ logger.debug(
+ "[JsonlWatcher] task exit error path=%s exc=%s",
+ self._path.name, exc,
+ )
+ self._task = None
+
+ async def _run(self) -> None:
+ # Wait for the file to appear. Claude writes the JSONL on first
+ # turn output; for first-spawn runs we may start watching
+ # before it exists.
+ while not self._path.exists():
+ if self._stopped.is_set():
+ return
+ await asyncio.sleep(self._poll_interval)
+
+ # Open in binary mode so partial UTF-8 sequences at the read
+ # boundary don't blow up — we accumulate bytes and decode on
+ # the newline split.
+ try:
+ handle = self._path.open("rb")
+ except OSError as exc:
+ logger.warning(
+ "[JsonlWatcher] open failed path=%s exc=%s",
+ self._path, exc,
+ )
+ return
+
+ buf = b""
+ try:
+ if self._start_from_end:
+ handle.seek(0, os.SEEK_END)
+
+ while not self._stopped.is_set():
+ chunk = handle.read()
+ if chunk:
+ buf += chunk
+ while b"\n" in buf:
+ raw, buf = buf.split(b"\n", 1)
+ await self._dispatch_line(raw)
+ else:
+ # No new data — sleep and try again. Use a small
+ # interval so latency stays comparable to stdout
+ # streaming.
+ try:
+ await asyncio.wait_for(
+ self._stopped.wait(),
+ timeout=self._poll_interval,
+ )
+ except asyncio.TimeoutError:
+ pass
+ except asyncio.CancelledError:
+ raise
+ except Exception as exc: # pragma: no cover — defensive
+ logger.warning(
+ "[JsonlWatcher] read loop ended unexpectedly path=%s exc=%s",
+ self._path.name, exc,
+ )
+ finally:
+ # Flush any final no-newline bytes (claude generally writes
+ # newline-terminated lines but be defensive).
+ if buf.strip():
+ await self._dispatch_line(buf)
+ try:
+ handle.close()
+ except OSError:
+ pass
+
+ async def _dispatch_line(self, raw: bytes) -> None:
+ text = raw.decode("utf-8", errors="replace").strip()
+ if not text:
+ return
+ try:
+ event: Dict[str, Any] = json.loads(text)
+ except json.JSONDecodeError:
+ return # garbage / partial line — drop silently
+ try:
+ await self._on_event(event)
+ except asyncio.CancelledError:
+ raise
+ except Exception as exc: # pragma: no cover — handler isolation
+ logger.warning(
+ "[JsonlWatcher] on_event handler raised path=%s exc=%s",
+ self._path.name, exc,
+ )
+
+
+class JsonlDirWatcher:
+ """Watch a directory for newly-appearing ``.jsonl`` files.
+
+ Used by :class:`services.cli_agent.session_pool.ClaudeSessionPool`
+ to capture the new session UUID after sending ``/clear``: claude
+ mints a fresh UUID and starts writing to
+ ``<project_key>/<new_uuid>.jsonl``; the watcher fires the callback
+ with that path, the pool reads the UUID off the filename, and
+ points its memory bridge at the new file.
+
+ Detection is "new file" only — we don't fire on appends to
+ existing files (that's :class:`JsonlWatcher`'s job). Files present
+ at :meth:`start` time are recorded as baseline and never fire the
+ callback.
+ """
+
+ __slots__ = (
+ "_dir", "_on_new_file", "_poll_interval",
+ "_task", "_stopped", "_baseline",
+ )
+
+ def __init__(
+ self,
+ directory: Path,
+ on_new_file: FileHandler,
+ *,
+ poll_interval: float = 0.25,
+ ) -> None:
+ self._dir = Path(directory)
+ self._on_new_file = on_new_file
+ self._poll_interval = max(0.05, float(poll_interval))
+ self._task: Optional[asyncio.Task[None]] = None
+ self._stopped = asyncio.Event()
+ self._baseline: Set[str] = set()
+
+ @property
+ def directory(self) -> Path:
+ return self._dir
+
+ async def start(self) -> None:
+ """Snapshot the current ``.jsonl`` files as the baseline, then
+ start polling. Files in the baseline never fire the callback."""
+ if self._task is not None and not self._task.done():
+ return
+ self._stopped.clear()
+ # Refresh baseline at every start so a re-used watcher across
+ # session-pool acquires sees a fresh snapshot.
+ self._baseline = self._snapshot()
+ self._task = asyncio.create_task(
+ self._run(),
+ name=f"JsonlDirWatcher({self._dir.name})",
+ )
+
+ async def stop(self) -> None:
+ self._stopped.set()
+ if self._task is None:
+ return
+ if not self._task.done():
+ self._task.cancel()
+ try:
+ await self._task
+ except asyncio.CancelledError:
+ pass
+ self._task = None
+
+ def _snapshot(self) -> Set[str]:
+ """Return the set of ``.jsonl`` filenames currently in the
+ directory. Empty set if the directory doesn't exist yet."""
+ try:
+ return {
+ entry.name for entry in self._dir.iterdir()
+ if entry.is_file() and entry.suffix == ".jsonl"
+ }
+ except (FileNotFoundError, NotADirectoryError):
+ return set()
+ except OSError as exc:
+ logger.debug(
+ "[JsonlDirWatcher] snapshot failed dir=%s exc=%s",
+ self._dir, exc,
+ )
+ return set()
+
+ async def _run(self) -> None:
+ # Wait for the directory to appear if it doesn't yet (first run
+ # before claude has materialised the projects dir).
+ while not self._dir.exists():
+ if self._stopped.is_set():
+ return
+ await asyncio.sleep(self._poll_interval)
+ # Note: if the directory appears mid-wait we re-snapshot at
+ # next iteration; first new file detected only AFTER the
+ # baseline is established, which matches the documented
+ # "files at start time are baseline" semantic.
+
+ while not self._stopped.is_set():
+ current = self._snapshot()
+ new = current - self._baseline
+ if new:
+ # Update baseline BEFORE firing the callback so a slow
+ # handler doesn't cause the same file to fire twice on
+ # the next tick. Order within the new set is undefined;
+ # callers shouldn't depend on ordering across multiple
+ # additions in one poll interval.
+ self._baseline |= new
+ for name in new:
+ path = self._dir / name
+ try:
+ await self._on_new_file(path)
+ except asyncio.CancelledError:
+ raise
+ except Exception as exc: # pragma: no cover
+ logger.warning(
+ "[JsonlDirWatcher] on_new_file handler raised "
+ "dir=%s file=%s exc=%s",
+ self._dir.name, name, exc,
+ )
+
+ try:
+ await asyncio.wait_for(
+ self._stopped.wait(),
+ timeout=self._poll_interval,
+ )
+ except asyncio.TimeoutError:
+ pass
+
+
+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.
+
+ Cheap helper so callers don't need to manually do ``path.stem`` and
+ validate. Claude's filenames are RFC-4122 UUIDs; we don't validate
+ the UUID format aggressively since claude controls the writer.
+ """
+ if path.suffix != ".jsonl":
+ return None
+ stem = path.stem
+ return stem if stem else None
diff --git a/server/services/cli_agent/protocol.py b/server/services/cli_agent/protocol.py
index ec12c608..e666861d 100644
--- a/server/services/cli_agent/protocol.py
+++ b/server/services/cli_agent/protocol.py
@@ -107,10 +107,13 @@ class AICliProvider(Protocol):
# 2) `npx --yes <package_name>` shim path
# Raises FileNotFoundError if neither is available.
- def headless_argv(self, task: Any, *, defaults: Dict[str, Any]) -> List[str]: ...
- # Build the full argv (binary + flags) for a headless run of
- # `task` (a `<Provider>TaskSpec` Pydantic model). `defaults`
- # comes from `ai_cli_providers.json` for this provider.
+ def interactive_argv(self, task: Any, *, defaults: Dict[str, Any]) -> List[str]: ...
+ # Build the full argv (binary + flags) for spawning a session
+ # over `task` (a `<Provider>TaskSpec` Pydantic model). For
+ # Claude, this is the interactive-TUI shape (no `-p`, prompt as
+ # positional after `--`); for Codex, it's `codex exec --json`
+ # since that's Codex's automation surface. `defaults` comes
+ # from `ai_cli_providers.json` for this provider.
# ---- native auth (no token wrapping) --------------------------------
diff --git a/server/services/cli_agent/providers/anthropic_claude.py b/server/services/cli_agent/providers/anthropic_claude.py
index d453f103..5fa81972 100644
--- a/server/services/cli_agent/providers/anthropic_claude.py
+++ b/server/services/cli_agent/providers/anthropic_claude.py
@@ -1,15 +1,40 @@
-"""Anthropic Claude Code CLI provider.
-
-Reference implementation for the `AICliProvider` Protocol. Full feature
-set: sessions, resume, budget, turns, allowed_tools, permission_mode,
-MCP lockfile, cost-in-JSON.
-
-Subprocess: ``claude -p <prompt> --output-format stream-json --verbose
---include-partial-messages --include-hook-events --ide
-[--session-id|--resume <UUID>] --model ... --max-turns ...
---max-budget-usd ... --allowedTools ... --permission-mode ...
---append-system-prompt ... [--effort ...] [--fallback-model ...]
-[--add-dir ...] [--disallowedTools ...] [--agent ...]``
+"""Anthropic Claude Code CLI provider — interactive TUI mode.
+
+Reference implementation for the `AICliProvider` Protocol. MachinaOs
+drives the same interactive `claude` invocation a normal user runs at
+their terminal — not `claude -p` headless. The PTY keeps the process
+alive in TUI mode while we read events from the on-disk session JSONL
+at ``<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session>.jsonl``
+instead of from stdout. See ``docs-internal/claude_code_interactive_mode.md``.
+
+Subprocess: ``claude --permission-mode bypassPermissions
+--allowedTools <list> [--model ...] [--append-system-prompt ...]
+[--mcp-config ...] [--strict-mcp-config] [--resume <UUID>]
+[--effort ...] [--add-dir ...] [--disallowedTools ...] [--agent ...]
+-- "<prompt>"``
+
+**Tools + skills are preserved**:
+ - ``--mcp-config`` registers MachinaOs's FastMCP server; the spawned
+ `claude` discovers `mcp__machinaos__*` tools via `tools/list`.
+ - ``--allowedTools`` carries the explicit allowlist (built-ins +
+ every wired MCP tool) — same shape as the prior headless path.
+ - Skills are still materialised under ``<cwd>/.claude/skills/`` by
+ ``AICliSession._materialise_skills`` (unchanged).
+
+**Permission mode**: ``bypassPermissions`` lets every allowlist entry
+fire without a TUI prompt — non-interactive automation has no human at
+the keyboard to click "Allow." Behaviorally equivalent to
+``--dangerously-skip-permissions`` but uses the documented permission
+mode (``code.claude.com/docs/en/permission-modes``) and is the same
+flag a Composio AO "permissionless" launch sets.
+
+Flags dropped in the interactive cutover (no longer emitted; the
+on-disk JSONL gives us the same data without `-p`):
+``-p / --print``, ``--output-format``, ``--verbose``,
+``--include-partial-messages``, ``--include-hook-events``,
+``--max-turns``, ``--max-budget-usd``, ``--session-id``,
+``--fallback-model``. ``--max-budget-usd`` / ``--max-turns`` become
+external monitors (Phase 2).
Binary + auth: shared with the auth surface via
``services.claude_oauth.claude_binary_path()`` — single project-local
@@ -17,9 +42,11 @@ install at ``<repo>/data/claude-machina/npm/`` and ``CLAUDE_CONFIG_DIR``
set on the spawn env so the agent picks up the same credentials the
Login button wrote.
-Final event: ``type == "result"`` carries ``total_cost_usd``,
-``duration_ms``, ``num_turns``, ``session_id``, and the assistant's
-``result`` string.
+Final event (parsed off disk by ``JsonlWatcher``): ``type == "result"``
+carries ``total_cost_usd``, ``duration_ms``, ``num_turns``,
+``session_id``, and the assistant's ``result`` string — same shape `-p`
+used to write to stdout (Claude Code CHANGELOG 2.1.101 / 2.1.126
+confirms the shared JSONL writer).
"""
from __future__ import annotations
@@ -71,7 +98,7 @@ class AnthropicClaudeProvider:
"""
return Path(claude_binary_path())
- def headless_argv(
+ def interactive_argv(
self,
task: Any, # ClaudeTaskSpec
*,
@@ -79,43 +106,50 @@ class AnthropicClaudeProvider:
mcp_endpoint_url: Optional[str] = None,
mcp_bearer_token: Optional[str] = None,
connected_tool_names: Optional[List[str]] = None,
+ include_prompt: bool = True,
) -> List[str]:
- """Build the full argv (binary + flags) for one task.
+ """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``.
``mcp_endpoint_url`` + ``mcp_bearer_token`` (if both set) are
emitted as a ``--mcp-config <json>`` block so the spawned
- ``claude -p`` registers MachinaOs's MCP server. The ``--ide`` /
- lockfile path is for interactive IDE-host scenarios; in headless
- mode the documented mechanism is ``--mcp-config`` (see
- https://code.claude.com/docs/en/mcp)."""
+ ``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`).
+ """
if not isinstance(task, ClaudeTaskSpec):
raise TypeError(
- "AnthropicClaudeProvider.headless_argv requires ClaudeTaskSpec, "
+ "AnthropicClaudeProvider.interactive_argv requires ClaudeTaskSpec, "
f"got {type(task).__name__}"
)
argv: List[str] = [str(self.binary_path())]
- argv += [
- "-p", task.prompt,
- "--output-format", "stream-json",
- "--verbose", # required by Claude CLI when using stream-json with --print
- "--include-partial-messages",
- "--include-hook-events", # surface SessionStart / hooks into stream-json
- ]
-
- # MCP server registration — headless path. The shape mirrors
- # the Claude Code MCP doc's ``mcp.json`` example and the
- # ``claude mcp add --transport http <name> <url> --header
- # "Authorization: Bearer ..."`` invocation.
+ # MCP server registration — same shape as the prior headless
+ # path; the Claude Code MCP doc's ``mcp.json`` example. Works
+ # identically in interactive mode.
if mcp_endpoint_url and mcp_bearer_token:
# `alwaysLoad: true` opts this server out of MCP tool-search
# deferral so all `mcp__machinaos__*` tools enter context at
# session start instead of waiting for a `ToolSearch` call
- # that the agent often doesn't make
+ # the agent often doesn't make
# (https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search).
- # Startup blocks <=5s waiting for the FastMCP connection;
- # acceptable since our server is already up before spawn.
mcp_payload = json.dumps({
"mcpServers": {
"machinaos": {
@@ -138,44 +172,20 @@ class AnthropicClaudeProvider:
)
argv += ["--model", model]
- # Session / resume — `resume_session_id` wins if both are set,
- # since "resume" implies the user has a prior session.
+ # Resume — no `--session-id` in interactive mode. First-run
+ # claude assigns its own UUID, which the JsonlDirWatcher
+ # discovers from the new file appearing under
+ # `<CLAUDE_CONFIG_DIR>/projects/<project_key>/` and which
+ # `_persist_memory` saves into `simpleMemory.last_session_id`.
if task.resume_session_id:
argv += ["--resume", task.resume_session_id]
- elif task.session_id:
- argv += ["--session-id", task.session_id]
-
- # Max turns
- max_turns = (
- task.max_turns
- if task.max_turns is not None
- else int(defaults.get(
- "default_max_turns",
- self._defaults.get("default_max_turns", 10),
- ))
- )
- argv += ["--max-turns", str(max_turns)]
-
- # Budget (USD)
- max_budget = (
- task.max_budget_usd
- if task.max_budget_usd is not None
- else float(defaults.get(
- "default_max_budget_usd",
- self._defaults.get("default_max_budget_usd", 5.0),
- ))
- )
- if max_budget > 0:
- argv += ["--max-budget-usd", str(max_budget)]
# Allowed tools — built-in defaults plus every workflow tool we
- # exposed via the per-batch FastMCP bridge. Without the
- # `mcp__machinaos__<name>` entries here, claude sees the tools
- # in `tools/list` but is denied permission when it tries to
- # invoke them ("I don't have permission to run a web search…")
- # because `--permission-mode acceptEdits` only auto-permits
- # Edit; everything else falls through to the allowlist.
- # Default fallback includes:
+ # exposed via the per-batch FastMCP bridge. Same shape as the
+ # prior headless argv. With ``--permission-mode bypassPermissions``
+ # (below) the allowlist becomes documentation-of-intent rather
+ # than an active gate, but we keep it explicit so the surface is
+ # auditable. Default fallback:
# - Read,Edit,Bash,Glob,Grep,Write — filesystem + shell escape hatches
# - Skill — invoke materialised `.claude/skills/<name>/SKILL.md`
# - WebSearch,WebFetch — escape hatches when no MCP tool matches
@@ -208,10 +218,18 @@ class AnthropicClaudeProvider:
if allowed_list:
argv += ["--allowedTools", ",".join(allowed_list)]
- # Permission mode (default acceptEdits)
+ # Permission mode — ``bypassPermissions`` for non-interactive
+ # automation. ``acceptEdits`` (the prior default) auto-permits
+ # Edit-class tools but prompts for everything else, which would
+ # hang the PTY since no human is present to approve.
+ # ``bypassPermissions`` is one of the documented permission
+ # modes (https://code.claude.com/docs/en/permission-modes) —
+ # behaviourally equivalent to ``--dangerously-skip-permissions``
+ # but uses the documented mode enum. Per-task override still
+ # honoured if the user explicitly wants ``acceptEdits``.
perm = task.permission_mode or defaults.get(
"default_permission_mode",
- self._defaults.get("default_permission_mode", "acceptEdits"),
+ self._defaults.get("default_permission_mode", "bypassPermissions"),
)
if perm:
argv += ["--permission-mode", perm]
@@ -248,11 +266,13 @@ class AnthropicClaudeProvider:
len(directive),
)
- # Optional per-task overrides (documented at code.claude.com/docs/en/cli-reference)
+ # Optional per-task overrides (work in interactive mode per
+ # code.claude.com/docs/en/cli-reference). ``--max-turns``,
+ # ``--max-budget-usd``, ``--fallback-model`` are ``-p``-only and
+ # not emitted; the task spec keeps the fields for back-compat
+ # but they're silently dropped here.
if task.effort:
argv += ["--effort", task.effort]
- if task.fallback_model:
- argv += ["--fallback-model", task.fallback_model]
for path in task.add_dir:
argv += ["--add-dir", path]
if task.disallowed_tools:
@@ -260,6 +280,14 @@ 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]
+
return argv
# ---- native auth -----------------------------------------------------
diff --git a/server/services/cli_agent/providers/google_gemini.py b/server/services/cli_agent/providers/google_gemini.py
index 3ec66fa5..eaeac5be 100644
--- a/server/services/cli_agent/providers/google_gemini.py
+++ b/server/services/cli_agent/providers/google_gemini.py
@@ -47,7 +47,16 @@ class GoogleGeminiProvider:
def binary_path(self) -> Path: # pragma: no cover
raise NotImplementedError
- def headless_argv(self, task: Any, *, defaults: Dict[str, Any]) -> List[str]: # pragma: no cover
+ def interactive_argv(
+ self,
+ task: Any,
+ *,
+ defaults: Dict[str, Any],
+ mcp_endpoint_url: Optional[str] = None,
+ mcp_bearer_token: Optional[str] = None,
+ connected_tool_names: Optional[List[str]] = None,
+ include_prompt: bool = True,
+ ) -> List[str]: # pragma: no cover
raise NotImplementedError
def login_argv(self) -> List[str]: # pragma: no cover
diff --git a/server/services/cli_agent/providers/openai_codex.py b/server/services/cli_agent/providers/openai_codex.py
index 3070f349..5c6e3a9e 100644
--- a/server/services/cli_agent/providers/openai_codex.py
+++ b/server/services/cli_agent/providers/openai_codex.py
@@ -97,15 +97,27 @@ class OpenAICodexProvider:
f"Install with: npm install -g {self.package_name}"
)
- def headless_argv(
+ def interactive_argv(
self,
task: Any, # CodexTaskSpec
*,
defaults: Dict[str, Any],
+ mcp_endpoint_url: Optional[str] = None,
+ mcp_bearer_token: Optional[str] = None,
+ connected_tool_names: Optional[List[str]] = None,
+ include_prompt: bool = True,
) -> List[str]:
+ """Build the codex spawn argv. Codex's automation surface is
+ ``codex exec --json`` (not a TUI mode like claude); this method
+ keeps the name aligned with the Protocol while emitting Codex's
+ documented non-interactive form. MCP bridging params are accepted
+ for Protocol uniformity but unused (codex's MCP config lives in
+ ``~/.codex/config.toml``). ``include_prompt`` is honoured so the
+ session pool can spawn without an initial prompt."""
+ _ = (mcp_endpoint_url, mcp_bearer_token, connected_tool_names)
if not isinstance(task, CodexTaskSpec):
raise TypeError(
- "OpenAICodexProvider.headless_argv requires CodexTaskSpec, "
+ "OpenAICodexProvider.interactive_argv requires CodexTaskSpec, "
f"got {type(task).__name__}"
)
@@ -144,11 +156,11 @@ class OpenAICodexProvider:
# System prompt — Codex doesn't have a dedicated --system-prompt
# flag in `exec`. Prepend it to the user prompt with a clear
# divider when present.
- prompt = task.prompt
- if task.system_prompt:
- prompt = f"<system>\n{task.system_prompt}\n</system>\n\n{task.prompt}"
-
- argv += [prompt]
+ if include_prompt and task.prompt:
+ prompt = task.prompt
+ if task.system_prompt:
+ prompt = f"<system>\n{task.system_prompt}\n</system>\n\n{task.prompt}"
+ argv += [prompt]
return argv
# ---- native auth -----------------------------------------------------
diff --git a/server/services/cli_agent/session.py b/server/services/cli_agent/session.py
index e86d18cd..a0f9437b 100644
--- a/server/services/cli_agent/session.py
+++ b/server/services/cli_agent/session.py
@@ -1,4 +1,4 @@
-"""One CLI session per task — `BaseProcessSupervisor` subclass.
+"""One CLI session per task — interactive PTY + on-disk JSONL events.
Each session is bound to:
- one provider (Claude or Codex)
@@ -6,18 +6,29 @@ Each session is bound to:
- one git worktree (created in `_pre_spawn`, removed in `cleanup`)
- one IDE lockfile (written in `_pre_spawn` when the provider supports it)
-Inherits `BaseProcessSupervisor`'s locked idempotent start/stop, recursive
-`kill_tree`, `terminate_then_kill(5s)` grace, and Windows
-`CTRL_BREAK_EVENT` path. We override `_do_start` to wire NDJSON consumers
-instead of the parent's generic `drain_stream(logger.info)`.
+**Transport / protocol split** (see
+``docs-internal/claude_code_interactive_mode.md``):
+
+ - Transport: a PTY (``ptyprocess`` on POSIX / ``pywinpty>=3.0.3`` on
+ Windows) keeps ``claude`` alive in TUI mode. The PTY's stdout —
+ ANSI-rendered TUI — is intentionally discarded.
+ - Protocol: events are read from the on-disk session JSONL at
+ ``<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session>.jsonl``,
+ same shape ``-p`` used to write to stdout (CHANGELOG 2.1.101 /
+ 2.1.126 confirms the shared writer).
+
+Inherits from :class:`BaseProcessSupervisor` for its idempotent locked
+start/stop machinery but overrides ``_do_start`` / ``_do_stop`` /
+``is_running`` to drive a :class:`PtyHandle` + :class:`JsonlWatcher`
+pair instead of a plain ``anyio.open_process``. ``self._proc`` stays
+``None`` for the whole session lifetime; the PTY handle is the
+authoritative process owner.
Sessions are NOT registered in the global supervisor registry — they're
-owned by `AICliService.run_batch()` for the lifetime of one batch.
+owned by ``AICliService.run_batch()`` for the lifetime of one batch.
-Liveness: relies on `wait_for_completion(timeout_seconds)` as the watchdog
-and the per-broadcast Temporal heartbeat fired by every
-`update_node_status()` call. We do not run our own per-second heartbeat
-loop or write diagnostic dump files.
+Liveness: ``wait_for_completion(timeout_seconds)`` waits for the JSONL
+``result`` event (signalled by ``_on_event`` setting an ``asyncio.Event``).
"""
from __future__ import annotations
@@ -25,9 +36,10 @@ from __future__ import annotations
import asyncio
import json
import os
+import re
import shutil
-import subprocess
import sys
+import time
import uuid
from pathlib import Path
from typing import Any, Dict, List, Optional
@@ -37,12 +49,25 @@ 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.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
from services.cli_agent.types import BaseAICliTaskSpec
logger = get_logger(__name__)
+# Claude derives its project_key from cwd by replacing every char that
+# isn't [a-zA-Z0-9.-] with `-`. Verified byte-for-byte against the
+# on-disk `~/.claude-machina/projects/` listing in the memory-bridge
+# research.
+_PROJECT_KEY_RE = re.compile(r"[^a-zA-Z0-9.-]")
+
+# How long to wait for claude to materialise its session JSONL after
+# spawn on a first-run (no `--resume`). Five seconds is generous —
+# under load the file usually appears within 200 ms.
+_FIRST_RUN_JSONL_TIMEOUT = 5.0
+
class AICliSession(BaseProcessSupervisor):
"""One CLI subprocess for one task."""
@@ -101,10 +126,18 @@ class AICliSession(BaseProcessSupervisor):
# Streaming state
self._events: List[Dict[str, Any]] = []
- self._stderr_lines: List[str] = []
+ self._stderr_lines: List[str] = [] # populated only on PTY error envelopes
self._exit_code: Optional[int] = None
self._lockfile_path: Optional[Path] = None
+ # PTY + JSONL state — set in `_do_start`, cleared in `_do_stop`.
+ self._pty_handle: Optional[PtyHandle] = None
+ self._jsonl_watcher: Optional[JsonlWatcher] = None
+ self._session_jsonl_path: Optional[Path] = None
+ # Signalled by `_on_event` when claude writes a `result` event;
+ # `wait_for_completion` awaits this.
+ self._result_event: asyncio.Event = asyncio.Event()
+
# ------------------------------------------------------------------
# Identity
# ------------------------------------------------------------------
@@ -133,7 +166,7 @@ class AICliSession(BaseProcessSupervisor):
return self._provider.binary_path()
def argv(self) -> List[str]:
- return self._provider.headless_argv(
+ return self._provider.interactive_argv(
self._task,
defaults=self._defaults,
mcp_endpoint_url=self._mcp_endpoint_url(),
@@ -302,7 +335,7 @@ class AICliSession(BaseProcessSupervisor):
)
# ------------------------------------------------------------------
- # _do_start: replace parent's drain tasks with NDJSON consumers
+ # _do_start: PTY spawn + JSONL watcher (interactive cutover)
# ------------------------------------------------------------------
async def _do_start(self) -> None:
@@ -312,97 +345,173 @@ class AICliSession(BaseProcessSupervisor):
await self._pre_spawn()
- kwargs: Dict[str, Any] = {
- "cwd": str(self.cwd()),
- "env": self.env(),
- # `claude -p` opens stdin to read piped input; we never pipe
- # anything, so without DEVNULL the CLI waits 3s and prints
- # "Warning: no stdin data received in 3s, proceeding without
- # it." Tools come over MCP, not stdin — close the handle
- # explicitly to skip the warning + the 3s stall.
- "stdin": subprocess.DEVNULL,
- "stdout": subprocess.PIPE,
- "stderr": subprocess.PIPE,
- }
- if sys.platform == "win32" and self.graceful_shutdown:
- kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP # type: ignore[attr-defined]
-
- self._proc = await anyio.open_process(self.argv(), **kwargs)
+ # The new path is claude-specific. Codex / Gemini's automation
+ # surface is `codex exec --json` / `gemini --output-format
+ # stream-json` — both write events to stdout, not disk — and
+ # need the legacy spawn path. For now claude is the only
+ # provider actually wired to a node plugin; once codex_agent
+ # ships, that branch grows here. We raise loudly if a non-
+ # claude provider tries to use this session class so the gap
+ # isn't silent.
+ if self._provider.name != "claude":
+ raise RuntimeError(
+ f"AICliSession (interactive PTY+JSONL) currently only "
+ f"supports the 'claude' provider; got "
+ f"{self._provider.name!r}. Codex / Gemini still use the "
+ f"stream-json-on-stdout path and need a separate session "
+ f"class — track via codex_agent plugin work."
+ )
+
+ # Where claude will write its session JSONL. The project_key is
+ # derived from cwd by the algorithm verified in the memory
+ # bridge research (every non-`[a-zA-Z0-9.-]` char → `-`).
+ project_dir = self._project_dir()
+ try:
+ project_dir.mkdir(parents=True, exist_ok=True)
+ except OSError as exc:
+ self._logger.warning(
+ "[%s] could not create project dir %s: %s",
+ self.label, project_dir, exc,
+ )
+
+ resume_uuid = getattr(self._task, "resume_session_id", None)
+ baseline_files: set[str] = set()
+ if resume_uuid:
+ # 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:
+ # First-run: snapshot the dir BEFORE spawn so we can
+ # identify the new file claude creates afterwards.
+ try:
+ baseline_files = {
+ p.name for p in project_dir.iterdir()
+ if p.suffix == ".jsonl"
+ }
+ except OSError:
+ pass
+
+ # 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.
+ transport = get_pty_transport()
+ argv = self.argv()
+ try:
+ self._pty_handle = await transport.spawn(
+ argv,
+ cwd=self.cwd() or self._repo_root,
+ env=self.env(),
+ )
+ except FileNotFoundError:
+ raise
+ except (OSError, RuntimeError) as exc:
+ raise RuntimeError(f"PTY spawn failed: {exc}") from exc
+
+ self._logger.info(
+ "[%s] spawned pid=%s task=%s branch=%s cwd=%s",
+ self.label, self._pty_handle.pid, self._task_id,
+ self._branch, self.cwd(),
+ )
+
+ # Resolve the JSONL path. For first-run we wait for claude to
+ # create the file; for resume the path is already known.
+ if self._session_jsonl_path is None:
+ try:
+ self._session_jsonl_path = await self._wait_for_new_jsonl(
+ project_dir, baseline_files,
+ )
+ except TimeoutError as exc:
+ # Surface a clean error envelope rather than letting the
+ # spawn limp on with no event source.
+ raise RuntimeError(str(exc)) from exc
+
self._logger.info(
- "[%s] spawned pid=%s task=%s branch=%s",
- self.label, self._proc.pid, self._task_id, self._branch,
+ "[%s] watching session JSONL: %s",
+ self.label, self._session_jsonl_path,
)
- # NDJSON consumers replace the parent's `drain_stream(logger.info)`.
- # We populate `self._drain_tasks` so the parent's `_do_stop`
- # cancels them on stop.
- self._drain_tasks = [
- asyncio.create_task(self._consume_stdout(self._proc.stdout)),
- asyncio.create_task(self._consume_stderr(self._proc.stderr)),
- ]
+ # Start the JSONL tail-f. Events flow into `_on_event` which
+ # also signals `self._result_event` when a `result` line lands.
+ # `start_from_end=False` so the watcher catches the `system/init`
+ # event claude writes immediately on startup (it's already on
+ # disk by the time we start watching).
+ self._jsonl_watcher = JsonlWatcher(
+ self._session_jsonl_path,
+ on_event=self._on_jsonl_event,
+ start_from_end=False,
+ )
+ await self._jsonl_watcher.start()
# ------------------------------------------------------------------
- # Stream consumers
+ # JSONL location helpers
# ------------------------------------------------------------------
- async def _consume_stdout(self, stream: Optional[anyio.abc.ByteReceiveStream]) -> None:
- if stream is None:
- return
- buf = b""
- try:
- async for chunk in stream:
- buf += chunk
- while b"\n" in buf:
- raw, buf = buf.split(b"\n", 1)
- text = raw.decode("utf-8", errors="replace").strip()
- if not text:
- continue
- event = self._provider.parse_event(text)
- if event is None:
- continue
- self._events.append(event)
- await self._on_event(event)
- if buf:
- text = buf.decode("utf-8", errors="replace").strip()
- if text:
- event = self._provider.parse_event(text)
- if event is not None:
- self._events.append(event)
- await self._on_event(event)
- except (anyio.ClosedResourceError, anyio.EndOfStream, asyncio.CancelledError):
- pass
- except Exception as exc: # pragma: no cover — defensive
- self._logger.debug("[%s] stdout consumer ended: %s", self.label, exc)
+ def _project_dir(self) -> Path:
+ """Return the dir where claude writes its session JSONLs for
+ our cwd. ``<MACHINA_CLAUDE_DIR>/projects/<project_key>/``.
+
+ Claude derives ``project_key`` by replacing every non-
+ ``[a-zA-Z0-9.-]`` char in ``str(cwd)`` with ``-``. Verified
+ byte-for-byte against the on-disk
+ ``data/claude-machina/projects/`` listing in the memory-bridge
+ research.
+ """
+ from services.claude_oauth import MACHINA_CLAUDE_DIR
+
+ cwd = self.cwd() or self._repo_root
+ project_key = _PROJECT_KEY_RE.sub("-", str(cwd))
+ return Path(MACHINA_CLAUDE_DIR) / "projects" / project_key
+
+ async def _wait_for_new_jsonl(
+ self, project_dir: Path, baseline: set[str],
+ ) -> Path:
+ """Poll ``project_dir`` for a new ``.jsonl`` file that wasn't
+ present in ``baseline``. Used on first-run spawns when we don't
+ know the UUID claude will assign. If multiple new files appear
+ (a race we don't expect), pick the newest by mtime.
+
+ Raises :class:`TimeoutError` after :data:`_FIRST_RUN_JSONL_TIMEOUT`
+ seconds — surfaces as a clean spawn failure rather than a
+ silently dead session.
+ """
+ deadline = time.monotonic() + _FIRST_RUN_JSONL_TIMEOUT
+ while time.monotonic() < deadline:
+ try:
+ current_files = {
+ p.name for p in project_dir.iterdir()
+ if p.suffix == ".jsonl"
+ }
+ except OSError:
+ current_files = set()
+ new_names = current_files - baseline
+ if new_names:
+ candidates = [project_dir / n for n in new_names]
+ # Pick newest by mtime — tolerates a stale baseline race
+ # where an unrelated session was deleted concurrently.
+ try:
+ return max(candidates, key=lambda p: p.stat().st_mtime)
+ except OSError:
+ return candidates[0]
+ await asyncio.sleep(0.1)
+ raise TimeoutError(
+ f"No session JSONL appeared under {project_dir} within "
+ f"{_FIRST_RUN_JSONL_TIMEOUT}s — claude may have failed to "
+ f"start or the CLAUDE_CONFIG_DIR is misconfigured."
+ )
- async def _consume_stderr(self, stream: Optional[anyio.abc.ByteReceiveStream]) -> None:
- if stream is None:
- return
- buf = b""
- try:
- async for chunk in stream:
- buf += chunk
- while b"\n" in buf:
- raw, buf = buf.split(b"\n", 1)
- text = raw.decode("utf-8", errors="replace").rstrip()
- if not text:
- continue
- self._stderr_lines.append(text)
- # Mirror to backend log too — without this the spawned
- # CLI's MCP-discovery / auth-failure / debug output
- # only reaches the Terminal panel, leaving the
- # operator log blind during runtime debugging.
- self._logger.info("[CC-Agent stderr] %s", text)
- await self._safe_terminal_log(text, level="error")
- if buf:
- text = buf.decode("utf-8", errors="replace").rstrip()
- if text:
- self._stderr_lines.append(text)
- self._logger.info("[CC-Agent stderr] %s", text)
- await self._safe_terminal_log(text, level="error")
- except (anyio.ClosedResourceError, anyio.EndOfStream, asyncio.CancelledError):
- pass
- except Exception as exc: # pragma: no cover
- self._logger.debug("[%s] stderr consumer ended: %s", self.label, exc)
+ async def _on_jsonl_event(self, event: Dict[str, Any]) -> None:
+ """JsonlWatcher callback: append + dispatch + result-signal.
+
+ Wraps the existing :meth:`_on_event` so the events list is
+ updated centrally and the result-event Asyncio primitive fires
+ when claude writes a `result` line — that's the signal that the
+ turn is done.
+ """
+ self._events.append(event)
+ await self._on_event(event)
+ if self._provider.is_final_event(event):
+ self._result_event.set()
# ------------------------------------------------------------------
# Event dispatch (UI broadcasts)
@@ -532,26 +641,76 @@ class AICliSession(BaseProcessSupervisor):
# Public lifecycle
# ------------------------------------------------------------------
+ def is_running(self) -> bool:
+ """Override BaseProcessSupervisor: we own the process via the
+ PTY handle, not ``self._proc``."""
+ return self._pty_handle is not None and self._pty_handle.is_alive()
+
+ async def _do_stop(self) -> None:
+ """Override BaseProcessSupervisor: stop the JSONL watcher and
+ kill the PTY child. Idempotent — clearing both refs prevents a
+ double-stop from racing the kill-cascade."""
+ watcher = self._jsonl_watcher
+ self._jsonl_watcher = None
+ if watcher is not None:
+ try:
+ await watcher.stop()
+ except Exception as exc: # pragma: no cover — defensive
+ self._logger.debug(
+ "[%s] watcher stop: %s", self.label, exc,
+ )
+
+ handle = self._pty_handle
+ self._pty_handle = None
+ if handle is not None:
+ pid = handle.pid
+ try:
+ await handle.kill()
+ except Exception as exc: # pragma: no cover — defensive
+ self._logger.debug(
+ "[%s] PTY kill: %s", self.label, exc,
+ )
+ self._logger.info("[%s] stopped pid=%s", self.label, pid)
+
async def wait_for_completion(self, timeout_seconds: int) -> SessionResult:
- """Wait for the CLI to exit, with hard timeout watchdog."""
- if self._proc is None:
+ """Wait for the JSONL ``result`` event with hard timeout.
+
+ In interactive mode the PTY process doesn't exit between turns
+ — claude stays alive waiting for the next user input. The
+ protocol contract is the ``result`` event on the JSONL: when
+ that lands, the turn is complete and we can collect the
+ outcome.
+
+ Hard timeout: matches the old stdout-driven behaviour. If the
+ result event doesn't arrive within ``timeout_seconds``, we
+ force-stop the PTY and surface a timeout error.
+ """
+ if self._pty_handle is None:
return self._build_result(
success=False, error="session never started",
)
try:
- await asyncio.wait_for(self._proc.wait(), timeout=timeout_seconds)
- self._exit_code = self._proc.returncode
- return self._build_result(success=(self._exit_code == 0))
+ await asyncio.wait_for(
+ self._result_event.wait(), timeout=timeout_seconds,
+ )
+ # The result event fired; claude wrote `result` on the JSONL.
+ # The subprocess is still alive (interactive TUI stays
+ # running) — we treat the turn as exit-code 0 since claude
+ # didn't crash.
+ self._exit_code = 0
+ return self._build_result(success=True)
except asyncio.TimeoutError:
await self.stop()
+ self._exit_code = -1
return self._build_result(
success=False,
error=f"timeout after {timeout_seconds}s",
)
async def cleanup(self) -> None:
- """Stop the process and remove the worktree + lockfile."""
+ """Stop the watcher + kill the PTY child and remove the
+ worktree + lockfile."""
try:
await self.stop()
except Exception as exc:
diff --git a/server/services/cli_agent/transports/__init__.py b/server/services/cli_agent/transports/__init__.py
new file mode 100644
index 00000000..c474a96d
--- /dev/null
+++ b/server/services/cli_agent/transports/__init__.py
@@ -0,0 +1,45 @@
+"""PTY transports for driving interactive CLI agents (claude) cross-platform.
+
+Public surface:
+
+ - ``PtyTransport`` / ``PtyHandle`` Protocols (in :mod:`.base`).
+ - ``get_pty_transport()`` factory picks the right backend for the
+ current platform — ``ptyprocess`` on POSIX, ``pywinpty>=3.0.3`` on
+ Windows. Both run in-process behind the same Protocol so the rest
+ of ``services/cli_agent/`` is platform-agnostic.
+
+If ``pywinpty`` / ``ptyprocess`` stability ever becomes an issue, the
+deferred upgrade path is an out-of-process Python pty-host subprocess
+(VSCode's ``ptyHostMain.ts`` pattern, in Python) — the Protocol
+boundary makes that swap cheap. See
+``docs-internal/claude_code_interactive_mode.md`` for the topology
+rationale.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .base import PtyHandle, PtyTransport
+
+__all__ = [
+ "PtyHandle",
+ "PtyTransport",
+ "get_pty_transport",
+]
+
+
+def get_pty_transport() -> PtyTransport:
+ """Return the appropriate ``PtyTransport`` for the current platform.
+
+ Lazy-imports the backend module so the heavy native dep (ptyprocess
+ on POSIX, pywinpty on Windows) is only loaded when something
+ actually needs to drive a PTY — keeps ``services.cli_agent``
+ importable in unit-test environments where the native dep may be
+ missing.
+ """
+ if sys.platform == "win32":
+ from .windows import WindowsPtyTransport
+ return WindowsPtyTransport()
+ from .posix import PosixPtyTransport
+ return PosixPtyTransport()
diff --git a/server/services/cli_agent/transports/base.py b/server/services/cli_agent/transports/base.py
new file mode 100644
index 00000000..bf1708ae
--- /dev/null
+++ b/server/services/cli_agent/transports/base.py
@@ -0,0 +1,111 @@
+"""Structural Protocols for PTY transports.
+
+Two interfaces:
+
+ - ``PtyTransport`` — factory for spawning. One per process; obtained
+ from :func:`services.cli_agent.transports.get_pty_transport`.
+ - ``PtyHandle`` — one live PTY-attached subprocess. Owns the PTY
+ pair (master + slave), the spawned process, and the lifecycle
+ primitives (write, kill, alive-check) the session pool needs.
+
+The handles are intentionally minimal — they expose only what the
+``ClaudeSessionPool`` and ``AICliSession`` need to drive an interactive
+``claude`` while reading events from the on-disk session JSONL. We
+never read PTY stdout in the steady state (the TUI's ANSI output is
+discarded), so ``read``/``recv`` are deliberately absent — adding them
+would invite the same TUI-scraping rabbit hole NousResearch's Hermes
+Agent is in.
+
+The Protocols are intentionally not declared ``@runtime_checkable``:
+``isinstance(x, PtyTransport)`` would pass any object with the right
+method names but is misleading for Protocols carrying behavioural
+contracts (lifecycle, threading guarantees). Static type-checkers
+still enforce structural conformance at the factory call site.
+"""
+
+from __future__ import annotations
+
+import signal
+from pathlib import Path
+from typing import Dict, List, Protocol
+
+
+class PtyHandle(Protocol):
+ """One live PTY-attached subprocess.
+
+ Implementations:
+ - :class:`services.cli_agent.transports.posix.PosixPtyHandle` —
+ wraps ``ptyprocess.PtyProcess``.
+ - :class:`services.cli_agent.transports.windows.WindowsPtyHandle` —
+ wraps ``pywinpty.PTY``.
+
+ Thread-safety: not promised. The session pool serialises access
+ under a per-key ``asyncio.Lock`` so concurrent writes / kills don't
+ race. Backends should still treat ``write`` as a single point-in-time
+ operation (no internal buffering across calls).
+ """
+
+ @property
+ def pid(self) -> int:
+ """OS pid of the spawned subprocess. Used by ``Job Object``
+ enrollment and the operator log."""
+
+ def is_alive(self) -> bool:
+ """``True`` while the subprocess is running, ``False`` after it
+ exits or is killed. Cheap to call (no syscall on the hot path
+ when possible)."""
+
+ async def write(self, data: bytes) -> None:
+ """Write raw bytes to the PTY master.
+
+ Used both for the user's prompt and for slash commands
+ (``/clear``, ``/compact``). Callers append the right line
+ terminator — typically ``b"\\r"`` for interactive mode (claude's
+ Ink TUI listens for Enter, not stdin-close; see
+ `claude-code#15553 <https://github.com/anthropics/claude-code/issues/15553>`_).
+ """
+
+ async def kill(self, signal_: int = signal.SIGTERM) -> None:
+ """Terminate the subprocess.
+
+ First-stage ``SIGTERM``; backends may escalate to ``SIGKILL``
+ after a grace window if the process doesn't exit on its own.
+ Windows ignores ``signal_`` and uses
+ ``TerminateProcess``/``CTRL_BREAK_EVENT`` semantics depending
+ on what the pywinpty handle supports.
+ """
+
+
+class PtyTransport(Protocol):
+ """Factory for spawning interactive subprocesses inside a PTY.
+
+ Implementations:
+ - :class:`services.cli_agent.transports.posix.PosixPtyTransport`
+ (uses ``ptyprocess``).
+ - :class:`services.cli_agent.transports.windows.WindowsPtyTransport`
+ (uses ``pywinpty>=3.0.3``).
+
+ There is one transport per process; ``services.cli_agent.transports
+ .get_pty_transport()`` picks the right one for the current platform.
+ """
+
+ async def spawn(
+ self,
+ argv: List[str],
+ *,
+ cwd: Path,
+ env: Dict[str, str],
+ ) -> PtyHandle:
+ """Spawn ``argv`` inside a fresh PTY pair under ``cwd`` with
+ the given ``env``.
+
+ Returns a live :class:`PtyHandle`. Raises ``FileNotFoundError``
+ if ``argv[0]`` isn't executable, ``OSError`` for PTY allocation
+ failures, and ``RuntimeError`` for backend-specific errors
+ (e.g. ConPTY not available on a too-old Windows build).
+
+ The handle is registered with the process tree supervisor
+ (:mod:`machina.tree` on Windows, ``os.setsid`` on POSIX) so the
+ child is reaped on host shutdown — see the existing
+ ``BaseProcessSupervisor`` patterns.
+ """
diff --git a/server/services/cli_agent/transports/posix.py b/server/services/cli_agent/transports/posix.py
new file mode 100644
index 00000000..3043d066
--- /dev/null
+++ b/server/services/cli_agent/transports/posix.py
@@ -0,0 +1,192 @@
+"""POSIX ``PtyTransport`` backed by ``ptyprocess``.
+
+``ptyprocess.PtyProcess.spawn(...)`` wraps ``os.forkpty()`` and returns
+a PtyProcess that owns the master fd. The child runs in its own
+session (``os.setsid()`` is the default), so SIGTERM-then-SIGKILL on the
+child pid reaps the whole TUI process group. We bridge ptyprocess's sync
+API to asyncio with ``loop.run_in_executor`` only at the spawn/kill
+boundary — writes are single fast syscalls and run on the event-loop
+thread.
+
+We do NOT register an ``loop.add_reader`` on the master fd: in the new
+architecture the on-disk session JSONL is the protocol surface; PTY
+stdout is rendered TUI we never look at. Keeping the read side empty
+means no buffering races between fd-readiness and JSONL-watcher events.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import signal
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from core.logging import get_logger
+
+from .base import PtyHandle, PtyTransport
+
+logger = get_logger(__name__)
+
+# How long to wait between SIGTERM and SIGKILL when killing a child.
+# Matches ``BaseProcessSupervisor.terminate_grace_seconds`` so the two
+# lifecycle layers agree on grace.
+_TERMINATE_GRACE_SECONDS = 5.0
+
+
+class PosixPtyHandle:
+ """ptyprocess-backed handle for one live ``claude`` subprocess."""
+
+ __slots__ = ("_proc", "_exited")
+
+ def __init__(self, proc: object) -> None:
+ # ``proc`` is a ``ptyprocess.PtyProcess`` but we keep it typed
+ # as ``object`` so the import remains lazy in :meth:`spawn`.
+ self._proc = proc
+ self._exited = False
+
+ @property
+ def pid(self) -> int:
+ return int(getattr(self._proc, "pid", -1))
+
+ def is_alive(self) -> bool:
+ if self._exited:
+ return False
+ try:
+ alive = bool(self._proc.isalive()) # type: ignore[attr-defined]
+ except Exception:
+ return False
+ if not alive:
+ self._exited = True
+ return alive
+
+ async def write(self, data: bytes) -> None:
+ # ptyprocess's write() is a single ``os.write`` call; fast
+ # enough to run on the event-loop thread.
+ if not data:
+ return
+ try:
+ self._proc.write(data) # type: ignore[attr-defined]
+ except OSError as exc:
+ # EIO = the slave end closed (process exited). Surface as a
+ # clean ConnectionError so callers can distinguish from a
+ # genuine permission / FD-leak bug.
+ raise ConnectionError(
+ f"PTY write failed (pid={self.pid}): {exc}"
+ ) from exc
+
+ async def kill(self, signal_: int = signal.SIGTERM) -> None:
+ """SIGTERM, wait briefly, escalate to SIGKILL if still alive.
+
+ Matches ``BaseProcessSupervisor.terminate_then_kill`` behaviour
+ and the grace window from the existing process-tree supervisor.
+ """
+ if self._exited:
+ return
+
+ loop = asyncio.get_running_loop()
+
+ # First-stage signal. ptyprocess exposes terminate(force=False)
+ # for SIGTERM and terminate(force=True) for SIGKILL. We want the
+ # SIGTERM-then-SIGKILL cascade with our own grace window so we
+ # call signal helpers directly.
+ try:
+ await loop.run_in_executor(
+ None, self._proc.kill, signal_, # type: ignore[attr-defined]
+ )
+ except (ProcessLookupError, OSError) as exc:
+ logger.debug("PTY first-stage signal raced exit: %s", exc)
+ self._exited = True
+ return
+
+ # Wait up to grace for graceful exit.
+ deadline = time.monotonic() + _TERMINATE_GRACE_SECONDS
+ while time.monotonic() < deadline:
+ if not self.is_alive():
+ self._exited = True
+ return
+ await asyncio.sleep(0.05)
+
+ # Escalate. ``kill(SIGKILL)`` is the documented force-quit path.
+ try:
+ await loop.run_in_executor(
+ None, self._proc.kill, signal.SIGKILL, # type: ignore[attr-defined]
+ )
+ except (ProcessLookupError, OSError):
+ pass
+ self._exited = True
+
+ # Drain the ptyprocess so the OS-level zombie is reaped on next
+ # alive-check. No-op if already reaped.
+ try:
+ await loop.run_in_executor(None, self._proc.close, True) # type: ignore[attr-defined]
+ except Exception:
+ pass
+
+
+class PosixPtyTransport(PtyTransport):
+ """Spawn factory using ``ptyprocess``.
+
+ Lazy-imports ``ptyprocess`` so test environments missing the dep
+ can still import :mod:`services.cli_agent.transports` (the factory
+ only loads this backend on POSIX). Raises ``RuntimeError`` if the
+ dep is genuinely missing at spawn time.
+ """
+
+ def __init__(self) -> None:
+ # Cache the imported class on first use so we don't repeat the
+ # try/except on every spawn.
+ self._pty_process_cls: Optional[object] = None
+
+ def _load_ptyprocess(self) -> object:
+ if self._pty_process_cls is not None:
+ return self._pty_process_cls
+ try:
+ from ptyprocess import PtyProcess # type: ignore[import-not-found]
+ except ImportError as exc:
+ raise RuntimeError(
+ "PosixPtyTransport requires the 'ptyprocess' package. "
+ "Install it (e.g. `pip install ptyprocess>=0.7.0`) — it's "
+ "declared in server/pyproject.toml with the marker "
+ "`sys_platform != 'win32'`."
+ ) from exc
+ self._pty_process_cls = PtyProcess
+ return PtyProcess
+
+ async def spawn(
+ self,
+ argv: List[str],
+ *,
+ cwd: Path,
+ env: Dict[str, str],
+ ) -> PtyHandle:
+ if not argv:
+ raise ValueError("PosixPtyTransport.spawn: empty argv")
+
+ PtyProcess = self._load_ptyprocess() # noqa: N806 — class name
+
+ binary = argv[0]
+ if not os.path.exists(binary):
+ # Mirror BaseProcessSupervisor's pre-spawn check so the
+ # error matches the existing operator-log shape.
+ raise FileNotFoundError(f"PTY binary not found: {binary}")
+
+ loop = asyncio.get_running_loop()
+ proc = await loop.run_in_executor(
+ None,
+ lambda: PtyProcess.spawn( # type: ignore[attr-defined]
+ argv,
+ cwd=str(cwd),
+ env=env,
+ # 80x24 default matches what Ink/most TUI libraries
+ # expect on a non-terminal-attached spawn. We don't
+ # render anywhere, so the dimensions are cosmetic.
+ dimensions=(24, 80),
+ ),
+ )
+ logger.info(
+ "[PtyTransport posix] spawned pid=%s cwd=%s argv0=%s",
+ getattr(proc, "pid", "?"), cwd, binary,
+ )
+ return PosixPtyHandle(proc)
diff --git a/server/services/cli_agent/transports/windows.py b/server/services/cli_agent/transports/windows.py
new file mode 100644
index 00000000..b584f7b7
--- /dev/null
+++ b/server/services/cli_agent/transports/windows.py
@@ -0,0 +1,175 @@
+"""Windows ``PtyTransport`` backed by ``pywinpty>=3.0.3``.
+
+``pywinpty`` v3.x is Rust-backed via PyO3 + winpty-rs + Maturin. Mirrors
+ptyprocess's high-level API closely (``PtyProcess.spawn(argv, cwd=,
+env=, dimensions=)``, ``write``, ``isalive``, ``kill``, ``close``) so
+this file's shape mirrors :mod:`.posix`. The pywinpty maintainers ship
+prebuilt wheels for Python 3.9-3.14 including free-threading, so
+end-users don't need a C++ build toolchain.
+
+Used in production by Jupyter Lab terminals and Spyder's IPython
+console — same production maturity bar as ptyprocess on POSIX. See
+the upgrade-path note in :mod:`services.cli_agent.transports` for the
+out-of-process pty-host fallback if pywinpty stability ever degrades.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import signal
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from core.logging import get_logger
+
+from .base import PtyHandle, PtyTransport
+
+logger = get_logger(__name__)
+
+# Match POSIX backend's grace window so the two lifecycle layers agree.
+_TERMINATE_GRACE_SECONDS = 5.0
+
+
+class WindowsPtyHandle:
+ """pywinpty-backed handle for one live ``claude`` subprocess."""
+
+ __slots__ = ("_proc", "_exited")
+
+ def __init__(self, proc: object) -> None:
+ self._proc = proc
+ self._exited = False
+
+ @property
+ def pid(self) -> int:
+ return int(getattr(self._proc, "pid", -1))
+
+ def is_alive(self) -> bool:
+ if self._exited:
+ return False
+ try:
+ alive = bool(self._proc.isalive()) # type: ignore[attr-defined]
+ except Exception:
+ return False
+ if not alive:
+ self._exited = True
+ return alive
+
+ async def write(self, data: bytes) -> None:
+ if not data:
+ return
+ # pywinpty's PtyProcess.write accepts bytes; defer the actual
+ # WriteFile to a worker thread because ConPTY can briefly block
+ # under back-pressure (https://github.com/microsoft/node-pty/issues/388).
+ loop = asyncio.get_running_loop()
+ try:
+ await loop.run_in_executor(
+ None, self._proc.write, data, # type: ignore[attr-defined]
+ )
+ except OSError as exc:
+ raise ConnectionError(
+ f"PTY write failed (pid={self.pid}): {exc}"
+ ) from exc
+
+ async def kill(self, signal_: int = signal.SIGTERM) -> None:
+ """First-stage WM_CLOSE / SIGTERM equivalent, wait briefly,
+ escalate to TerminateProcess if still alive.
+
+ Windows doesn't have POSIX signals; pywinpty maps the
+ ``kill(signal_)`` call to the closest analogue (TerminateProcess
+ with the exit code, or ``CTRL_BREAK_EVENT`` when the process
+ was spawned into its own console group). ``force=True`` is the
+ unconditional escalation.
+ """
+ if self._exited:
+ return
+
+ loop = asyncio.get_running_loop()
+
+ try:
+ await loop.run_in_executor(
+ None, self._proc.kill, signal_, # type: ignore[attr-defined]
+ )
+ except (ProcessLookupError, OSError) as exc:
+ logger.debug("ConPTY first-stage signal raced exit: %s", exc)
+ self._exited = True
+ return
+
+ deadline = time.monotonic() + _TERMINATE_GRACE_SECONDS
+ while time.monotonic() < deadline:
+ if not self.is_alive():
+ self._exited = True
+ return
+ await asyncio.sleep(0.05)
+
+ # Escalate. ``close(force=True)`` calls TerminateProcess on the
+ # child and frees the ConPTY handle.
+ try:
+ await loop.run_in_executor(None, self._proc.close, True) # type: ignore[attr-defined]
+ except (ProcessLookupError, OSError):
+ pass
+ self._exited = True
+
+
+class WindowsPtyTransport(PtyTransport):
+ """Spawn factory using ``pywinpty>=3.0.3``.
+
+ Lazy-imports ``winpty`` (the importable package name for pywinpty)
+ so test environments missing the dep can still import this module
+ on non-Windows; the factory in
+ :mod:`services.cli_agent.transports` only loads this backend when
+ ``sys.platform == 'win32'``.
+ """
+
+ def __init__(self) -> None:
+ self._pty_process_cls: Optional[object] = None
+
+ def _load_winpty(self) -> object:
+ if self._pty_process_cls is not None:
+ return self._pty_process_cls
+ try:
+ from winpty import PtyProcess # type: ignore[import-not-found]
+ except ImportError as exc:
+ raise RuntimeError(
+ "WindowsPtyTransport requires 'pywinpty>=3.0.3'. "
+ "Install it (e.g. `pip install pywinpty>=3.0.3`) — it's "
+ "declared in server/pyproject.toml with the marker "
+ "`sys_platform == 'win32'`. Prebuilt wheels are "
+ "available for Python 3.9-3.14; no C++ toolchain "
+ "required."
+ ) from exc
+ self._pty_process_cls = PtyProcess
+ return PtyProcess
+
+ async def spawn(
+ self,
+ argv: List[str],
+ *,
+ cwd: Path,
+ env: Dict[str, str],
+ ) -> PtyHandle:
+ if not argv:
+ raise ValueError("WindowsPtyTransport.spawn: empty argv")
+
+ PtyProcess = self._load_winpty() # noqa: N806
+
+ binary = argv[0]
+ if not os.path.exists(binary):
+ raise FileNotFoundError(f"PTY binary not found: {binary}")
+
+ loop = asyncio.get_running_loop()
+ proc = await loop.run_in_executor(
+ None,
+ lambda: PtyProcess.spawn( # type: ignore[attr-defined]
+ argv,
+ cwd=str(cwd),
+ env=env,
+ dimensions=(24, 80),
+ ),
+ )
+ logger.info(
+ "[PtyTransport windows] spawned pid=%s cwd=%s argv0=%s",
+ getattr(proc, "pid", "?"), cwd, binary,
+ )
+ return WindowsPtyHandle(proc)
diff --git a/server/tests/services/cli_agent/test_providers.py b/server/tests/services/cli_agent/test_providers.py
index 513fc44b..6badaea4 100644
--- a/server/tests/services/cli_agent/test_providers.py
+++ b/server/tests/services/cli_agent/test_providers.py
@@ -1,8 +1,11 @@
"""Unit tests for `AnthropicClaudeProvider` and `OpenAICodexProvider`.
Covers:
- - `headless_argv` shape (every flag in the right place, defaults
- applied, optional fields omitted when unset)
+ - `interactive_argv` shape (every flag in the right place, defaults
+ applied, optional fields omitted when unset). Claude's argv no
+ longer carries ``-p``/``--output-format``/``--max-turns``/
+ ``--max-budget-usd``/``--session-id``/``--include-hook-events`` —
+ interactive cutover ($docs-internal/claude_code_interactive_mode.md).
- `parse_event` round-trips JSON correctly, returns None for garbage
- `is_final_event` matches the right event types
- `event_to_session_result` reconstructs cost / session_id /
@@ -70,56 +73,77 @@ def claude_provider():
class TestClaudeArgv:
def test_minimum_required_flags(self, claude_provider):
task = ClaudeTaskSpec(prompt="hello world")
- argv = claude_provider.headless_argv(task, defaults={})
- # `-p hello world` must be present
- assert "-p" in argv
+ argv = claude_provider.interactive_argv(task, defaults={})
+ # Prompt is the positional after `--` (interactive mode). No
+ # `-p` / `--print` / `--output-format stream-json` anymore.
+ 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
- # stream-json output format
- assert "--output-format" in argv
- assert "stream-json" in argv
+ # Ordering: `--` immediately precedes the prompt.
+ sep_idx = argv.index("--")
+ assert argv[sep_idx + 1] == "hello world"
# Defaults applied
assert "--model" in argv
assert "claude-sonnet-4-6" in argv # default_model from JSON
- assert "--max-turns" in argv
- assert "10" in argv # default_max_turns
- assert "--max-budget-usd" in argv
- assert "5.0" in argv # default_max_budget_usd
+ # `-p`-only flags no longer emitted
+ 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
-
- def test_session_id_flag(self, claude_provider):
+ # `bypassPermissions` is the documented mode for non-interactive
+ # automation (https://code.claude.com/docs/en/permission-modes).
+ perm_idx = argv.index("--permission-mode")
+ assert argv[perm_idx + 1] == "bypassPermissions"
+
+ def test_no_session_id_flag_in_interactive(self, claude_provider):
+ """Claude assigns its own session UUID in interactive mode; we
+ no longer pre-mint a UUID and pass it via `--session-id`. The
+ `session_id` field on ClaudeTaskSpec is kept for back-compat
+ but silently dropped from argv."""
task = ClaudeTaskSpec(prompt="x", session_id="sess-abc-123")
- argv = claude_provider.headless_argv(task, defaults={})
- assert "--session-id" in argv
- assert "sess-abc-123" in argv
- assert "--resume" not in argv
+ argv = claude_provider.interactive_argv(task, defaults={})
+ assert "--session-id" not in argv
- def test_resume_wins_over_session_id(self, claude_provider):
+ def test_resume_flag_emitted(self, claude_provider):
task = ClaudeTaskSpec(
prompt="x",
- session_id="new-sess",
+ session_id="new-sess", # silently dropped in interactive
resume_session_id="prior-sess",
)
- argv = claude_provider.headless_argv(task, defaults={})
+ argv = claude_provider.interactive_argv(task, defaults={})
assert "--resume" in argv
assert "prior-sess" in argv
assert "--session-id" not in argv
- def test_zero_budget_omits_flag(self, claude_provider):
- task = ClaudeTaskSpec(prompt="x", max_budget_usd=0.0)
- argv = claude_provider.headless_argv(task, defaults={})
- assert "--max-budget-usd" not in argv
-
def test_system_prompt_propagates(self, claude_provider):
task = ClaudeTaskSpec(prompt="x", system_prompt="be concise")
- argv = claude_provider.headless_argv(task, defaults={})
+ argv = claude_provider.interactive_argv(task, defaults={})
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(
+ task, defaults={}, include_prompt=False,
+ )
+ assert "--" not in argv
+ assert "will-be-piped-to-pty" not in argv
+
def test_wrong_task_type_raises(self, claude_provider):
codex_task = CodexTaskSpec(prompt="x")
with pytest.raises(TypeError, match="ClaudeTaskSpec"):
- claude_provider.headless_argv(codex_task, defaults={})
+ claude_provider.interactive_argv(codex_task, defaults={})
class TestClaudeParseEvent:
@@ -271,7 +295,7 @@ def codex_provider():
class TestCodexArgv:
def test_no_session_no_budget_no_turns(self, codex_provider):
task = CodexTaskSpec(prompt="hello")
- argv = codex_provider.headless_argv(task, defaults={})
+ argv = codex_provider.interactive_argv(task, defaults={})
assert "--max-turns" not in argv
assert "--max-budget-usd" not in argv
assert "--session-id" not in argv
@@ -280,25 +304,25 @@ class TestCodexArgv:
def test_sandbox_flag(self, codex_provider):
task = CodexTaskSpec(prompt="x", sandbox="read-only")
- argv = codex_provider.headless_argv(task, defaults={})
+ argv = codex_provider.interactive_argv(task, defaults={})
assert "--sandbox" in argv
assert "read-only" in argv
def test_ask_for_approval_flag(self, codex_provider):
task = CodexTaskSpec(prompt="x", ask_for_approval="on-request")
- argv = codex_provider.headless_argv(task, defaults={})
+ argv = codex_provider.interactive_argv(task, defaults={})
assert "--ask-for-approval" in argv
assert "on-request" in argv
def test_default_sandbox_workspace_write(self, codex_provider):
task = CodexTaskSpec(prompt="x")
- argv = codex_provider.headless_argv(task, defaults={})
+ argv = codex_provider.interactive_argv(task, defaults={})
idx = argv.index("--sandbox")
assert argv[idx + 1] == "workspace-write"
def test_system_prompt_prepended(self, codex_provider):
task = CodexTaskSpec(prompt="user thing", system_prompt="be careful")
- argv = codex_provider.headless_argv(task, defaults={})
+ argv = codex_provider.interactive_argv(task, defaults={})
# Codex has no --system-prompt flag; we prepend with <system> tags
prompt_arg = argv[-1] # last arg is the prompt
assert "<system>" in prompt_arg
@@ -308,7 +332,7 @@ class TestCodexArgv:
def test_wrong_task_type_raises(self, codex_provider):
claude_task = ClaudeTaskSpec(prompt="x")
with pytest.raises(TypeError, match="CodexTaskSpec"):
- codex_provider.headless_argv(claude_task, defaults={})
+ codex_provider.interactive_argv(claude_task, defaults={})
class TestCodexEventReconstruction: