Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(cli_agent): interactive PTY + on-disk JSONL replaces `-p` headless (Steps 1-4)
trohitg05905eff1a98
diff --git a/server/pyproject.toml b/server/pyproject.tomlindex 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.pynew file mode 100644index 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 Nonediff --git a/server/services/cli_agent/protocol.py b/server/services/cli_agent/protocol.pyindex 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.pyindex 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 theLogin 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) areemitted 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.pyindex 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 coverraise 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 coverraise NotImplementedErrordef login_argv(self) -> List[str]: # pragma: no coverdiff --git a/server/services/cli_agent/providers/openai_codex.py b/server/services/cli_agent/providers/openai_codex.pyindex 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.pyindex 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 annotationsimport asyncioimport jsonimport os+import reimport shutil-import subprocessimport sys+import timeimport uuidfrom pathlib import Pathfrom typing import Any, Dict, List, Optional@@ -37,12 +49,25 @@ import yamlfrom core.logging import get_loggerfrom services._supervisor.process import BaseProcessSupervisor+from services.cli_agent.jsonl_watcher import JsonlWatcherfrom services.cli_agent.lockfile import remove_ide_lockfile, write_ide_lockfilefrom services.cli_agent.protocol import AICliProvider, CanonicalUsage, SessionResult+from services.cli_agent.transports import PtyHandle, get_pty_transportfrom services.cli_agent.types import BaseAICliTaskSpeclogger = 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 stateself._events: List[Dict[str, Any]] = []- self._stderr_lines: List[str] = []+ self._stderr_lines: List[str] = [] # populated only on PTY error envelopesself._exit_code: Optional[int] = Noneself._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 = -1return 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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 argvassert "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 appliedassert "--model" in argvassert "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 preservedassert "--allowedTools" in argvassert "--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 interactiveresume_session_id="prior-sess",)- argv = claude_provider.headless_argv(task, defaults={})+ argv = claude_provider.interactive_argv(task, defaults={})assert "--resume" in argvassert "prior-sess" in argvassert "--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 argvassert "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 argvassert "--max-budget-usd" not in argvassert "--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 argvassert "read-only" in argvdef 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 argvassert "on-request" in argvdef 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> tagsprompt_arg = argv[-1] # last arg is the promptassert "<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: