baserun-cli 0.1.0__tar.gz

baserun_cli-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: baserun-cli
+Version: 0.1.0
+Summary: BaseRun agent-side daemon (connects to nchan, spawns CLI agents, publishes run events)
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=13.0
+Requires-Dist: httpx>=0.27.0
+
+# baserun-cli
+
+BaseRun agent-side daemon. It connects to the BaseRun nchan channel, runs local CLI agents, and publishes run events back to BaseRun.
+
+## Run
+
+```bash
+NCHAN_URL="wss://baserun.livesig.cn/nchan" \
+AGENT_APP_ID="<agent_id>" \
+AGENT_APP_SECRET="<agent_secret>" \
+CONNECTOR_TYPE="claude_code" \
+uvx baserun-cli
+```
+
+`CONNECTOR_TYPE` defaults to `claude_code`.
+
+## Build
+
+```bash
+cd baserun-cli
+rm -rf dist build *.egg-info
+python3 -m build
+```
+
+## Publish
+
+```bash
+cd baserun-cli
+python3 -m twine upload dist/*
+```
+
+Or with uv:
+
+```bash
+cd baserun-cli
+uv build
+uv publish
+```

baserun_cli-0.1.0/README.md

@@ -0,0 +1,38 @@
+# baserun-cli
+
+BaseRun agent-side daemon. It connects to the BaseRun nchan channel, runs local CLI agents, and publishes run events back to BaseRun.
+
+## Run
+
+```bash
+NCHAN_URL="wss://baserun.livesig.cn/nchan" \
+AGENT_APP_ID="<agent_id>" \
+AGENT_APP_SECRET="<agent_secret>" \
+CONNECTOR_TYPE="claude_code" \
+uvx baserun-cli
+```
+
+`CONNECTOR_TYPE` defaults to `claude_code`.
+
+## Build
+
+```bash
+cd baserun-cli
+rm -rf dist build *.egg-info
+python3 -m build
+```
+
+## Publish
+
+```bash
+cd baserun-cli
+python3 -m twine upload dist/*
+```
+
+Or with uv:
+
+```bash
+cd baserun-cli
+uv build
+uv publish
+```

baserun_cli-0.1.0/baserun_cli/_vendored/__init__.py

@@ -0,0 +1,28 @@
+"""Vendored copy of the server's connector layer (CLISpec + CLIAgentConnector + parsers).
+
+Kept in sync with backend/app/connectors/{base,cli,parsers}.py. The agent client
+needs the spawn+parse logic but not the server's other deps (DB, FastAPI, Feishu).
+
+If these drift, prefer syncing FROM backend TO here.
+"""
+from .base import (  # noqa: F401
+    BUILTIN_SPECS,
+    CLISpec,
+    ConnectorEvent,
+    ConnectorEventType,
+    HealthResult,
+    get_connector,
+    resolve_spec,
+)
+from .cli import CLIAgentConnector  # noqa: F401
+
+__all__ = [
+    "BUILTIN_SPECS",
+    "CLISpec",
+    "ConnectorEvent",
+    "ConnectorEventType",
+    "HealthResult",
+    "get_connector",
+    "resolve_spec",
+    "CLIAgentConnector",
+]

baserun_cli-0.1.0/baserun_cli/_vendored/base.py

@@ -0,0 +1,218 @@
+"""AgentConnector abstraction.
+
+A connector drives one kind of agent. The host spawns the agent process
+on-demand; session state persists in the agent's own session store and is
+addressed by `agent_session_id`.
+
+CONNECTION CONTRACT. An agent is integrable as a spawn-mode connector iff its
+CLI exposes:
+  1. one-shot headless execution:    `<bin> <prompt_flag> "<input>"`
+  2. resume an existing session:     `... <resume_flag> <session_id>`
+  3. structured streaming output:    `... <output_format_flag>` (e.g. stream-json)
+  4. (optional) native fork:         `... <fork_flag>` — copies parent history
+                                       into a new session id. If absent, the host
+                                       falls back to rebuild_path_history().
+
+Claude Code and Codex both fit (Codex lacks #4). OpenClaw does NOT fit this
+contract (its CLI is a gateway client + has no fork flag) — see README.
+
+The contract is expressed as data (a CLISpec), not as code per agent. Adding a
+new compatible agent = adding a CLISpec, no new class.
+"""
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator
+
+
+class ConnectorEventType(str, enum.Enum):
+    SESSION = "session"       # {agent_session_id, mode: new|resume|fork|fallback}
+    THINKING = "thinking"     # {delta}
+    TOOL_CALL = "tool_call"   # {tool, args, call_id}
+    TOOL_RESULT = "tool_result"  # {call_id, result}
+    MESSAGE = "message"       # {delta}
+    FINAL = "final"           # {text, session_id}
+    ERROR = "error"           # {message}
+    USAGE = "usage"           # {input, output, total}
+
+
+@dataclass
+class ConnectorEvent:
+    type: ConnectorEventType
+    payload: dict[str, Any]
+
+
+@dataclass
+class HealthResult:
+    ok: bool
+    detail: str = ""
+    status: str = "online"  # short label for the Bitable status field
+
+
+@dataclass
+class ForkShape:
+    """How a native fork is expressed on the CLI.
+
+    Three shapes cover the real CLIs:
+      - flag_overlay (Claude Code): resume + an extra flag, single command.
+            `claude -p "<p>" --resume <sid> --fork-session`  → streams jsonl
+      - two_step (Codex): step 1 creates a forked session (returns its id),
+        step 2 resumes into it headless. Lets a TUI-only `fork` subcommand
+        still achieve headless native fork via `exec resume`.
+            step1: `codex fork <sid>`           → new session id (from output)
+            step2: `codex exec resume <new> -p` → streams jsonl
+      - subcommand: a single subcommand taking sid+prompt positionally.
+            `codex fork <sid> "<p>"` (headless variant, if it ever ships)
+
+    `headless` indicates whether this fork form can run non-interactively AND
+    emit the streaming structured output our subprocess parser expects. If
+    False, the host treats native_fork as unavailable and falls back to rebuild.
+    """
+
+    shape: str = "flag_overlay"  # "flag_overlay" | "two_step" | "subcommand"
+    # flag_overlay: the extra flag appended after --resume <sid>
+    flag: str = "--fork-session"
+    # subcommand: the subcommand name (e.g. "fork"); sid+prompt are positional
+    subcommand: str = "fork"
+    # two_step fields:
+    #   step1 command template (bin is prepended). Use {sid} placeholder.
+    #   e.g. "fork {sid}" → `<bin> fork <sid>`
+    fork_cmd: str = "fork {sid}"
+    #   step2 command template: how to resume into the new session headless.
+    #   Use {sid} (the NEW session id from step1) and {prompt} placeholders.
+    #   e.g. "exec resume {sid} {prompt}" → `<bin> exec resume <new> "<p>"`
+    resume_cmd: str = "exec resume {sid} {prompt}"
+    #   regex to extract the new session id from step1's combined stdout/stderr.
+    #   Matches the first UUID found by default.
+    id_pattern: str = r"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})"
+    # whether this fork form works headless + structured-output (our requirement)
+    headless: bool = True
+
+
+@dataclass
+class CLISpec:
+    """The connection contract as data. Drives a single generic connector.
+
+    Fields map to CLI flags/behaviour. Anything not declared is assumed absent
+    (e.g. fork=None → no native fork, host uses fallback rebuild).
+    """
+
+    # which output parser to use: "claude" | "codex" | ... (strategy selector)
+    output_schema: str = "claude"
+    # the executable name or path
+    bin: str = "claude"
+    # how to pass the prompt and turn on streaming structured output
+    prompt_flag: str = "-p"
+    output_format_flag: tuple[str, ...] = ("--output-format", "stream-json")
+    # extra flags always passed (e.g. --verbose for claude stream-json)
+    base_flags: list[str] = field(default_factory=lambda: ["--verbose"])
+    # resume: flag + whether it takes the session id as an argument
+    resume_flag: str | None = "--resume"
+    # resume via subcommand (e.g. codex: `exec resume <sid> <prompt>` instead of `exec <prompt> --resume <sid>`)
+    resume_subcommand: str | None = None
+    # native fork (optional). None → not supported, host falls back.
+    fork: ForkShape | None = None
+    # workdir / env injected into the subprocess
+    workdir: str | None = None
+    env: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def native_fork(self) -> bool:
+        """True iff a headless native fork is available."""
+        return self.fork is not None and self.fork.headless
+
+
+# ---------------------------------------------------------------------- specs
+# Known agent specs. Keyed by the value stored in Agent.connector_type / config.
+# Users can also supply a full CLISpec inline in Agent.config to add a new
+# compatible agent without touching code here.
+BUILTIN_SPECS: dict[str, CLISpec] = {
+    "claude_code": CLISpec(
+        output_schema="claude",
+        bin="claude",
+        prompt_flag="-p",
+        output_format_flag=("--output-format", "stream-json"),
+        base_flags=["--verbose", "--include-partial-messages", "--dangerously-skip-permissions"],
+        resume_flag="--resume",
+        fork=ForkShape(shape="flag_overlay", flag="--fork-session", headless=True),
+    ),
+    "codex": CLISpec(
+        output_schema="codex",
+        bin="codex",
+        prompt_flag="exec",  # `codex exec "<prompt>"`
+        output_format_flag=("--json",),
+        base_flags=["--full-auto"],  # sandboxed auto-execution (like Claude's --dangerously-skip-permissions)
+        resume_flag=None,  # Codex resume is a subcommand, not a flag
+        resume_subcommand="resume",  # `codex exec resume <sid> <prompt> --json`
+        # codex fork is TUI-only (`codex fork`), cannot run headless.
+        # Host falls back to rebuild_path_history for fork.
+        fork=None,
+    ),
+    "bash_agent": CLISpec(
+        output_schema="bash_agent",
+        bin="ccagent",  # actual binary; can also be bash-agent, rustagent, etc.
+        prompt_flag="",  # positional prompt (no flag prefix)
+        output_format_flag=("--output", "stream-json"),
+        base_flags=[],
+        resume_flag="--session",
+        fork=ForkShape(shape="flag_overlay", flag="--fork", headless=True),
+    ),
+}
+
+
+def resolve_spec(connector_type: str, config: dict[str, Any]) -> CLISpec:
+    """Build a CLISpec from a builtin, overlaid with per-agent config overrides.
+
+    config may contain any CLISpec field to override the builtin (e.g. a custom
+    bin path, or workdir/env). It may also contain a full `cli_spec` dict to
+    define an entirely new agent not in BUILTIN_SPECS.
+    """
+    spec = BUILTIN_SPECS.get(connector_type)
+    if spec is None:
+        # allow a brand-new agent defined entirely in config
+        raw = config.get("cli_spec") or {}
+        spec = CLISpec(output_schema=connector_type)
+    else:
+        from dataclasses import replace
+
+        spec = replace(spec)  # copy so we don't mutate the builtin
+
+    # apply config overrides (env/workdir most common)
+    overrides = config.get("cli_spec") if "cli_spec" in config else config
+    for fld in ("bin", "prompt_flag", "resume_flag", "resume_subcommand", "fork", "workdir", "env", "base_flags", "output_schema"):
+        if fld in overrides:
+            setattr(spec, fld, overrides[fld])
+    return spec
+
+
+# ------------------------------------------------------------------ connector
+class AgentConnector:
+    """Generic spawn-mode connector driven by a CLISpec."""
+
+    def __init__(self, spec: CLISpec, config: dict[str, Any] | None = None) -> None:
+        self.spec = spec
+        self.config = config or {}
+
+    @property
+    def capabilities(self) -> dict[str, bool]:
+        return {
+            "native_resume": self.spec.resume_flag is not None,
+            "native_fork": self.spec.native_fork,
+        }
+
+    # -------------------------------------------------------------- factories
+    @classmethod
+    def for_type(cls, connector_type: str, config: dict[str, Any]) -> "AgentConnector":
+        return cls(resolve_spec(connector_type, config), config)
+
+
+def get_connector(connector_type: str, config: dict[str, Any]) -> "CLIAgentConnector":
+    """Factory used by the rest of the system. Returns the generic CLI connector."""
+    from .cli import CLIAgentConnector
+
+    return CLIAgentConnector.for_type(connector_type, config)
+
+
+# re-export the streaming protocol so callers can type-hint against it
+AsyncEventIterator = AsyncIterator[ConnectorEvent]

baserun_cli-0.1.0/baserun_cli/_vendored/cli.py

@@ -0,0 +1,332 @@
+"""Generic spawn-mode CLI connector, driven entirely by a CLISpec.
+
+This single class replaces the previous per-agent ClaudeCodeConnector /
+CodexConnector classes. All flag-assembly and process management is shared;
+only the output-line parser is selected by CLISpec.output_schema (see parsers.py).
+
+Adding a new compatible agent = adding a CLISpec (in base.BUILTIN_SPECS or
+inline in Agent.config). No new class, no new file.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+from typing import AsyncIterator
+
+from .base import (
+    AgentConnector,
+    ConnectorEvent,
+    ConnectorEventType,
+    HealthResult,
+)
+from .parsers import extract_session_id, parse_line
+
+
+class CLIAgentConnector(AgentConnector):
+    """The one connector implementation for all spec-compatible CLI agents."""
+
+    # ---------------------------------------------------------------- health
+    async def health(self) -> HealthResult:
+        cli = shutil.which(self.spec.bin) or (
+            self.spec.bin if os.path.exists(self.spec.bin) else None
+        )
+        if not cli:
+            return HealthResult(
+                ok=False, status="offline", detail=f"CLI not found: {self.spec.bin}"
+            )
+        if self.spec.workdir and not os.path.isdir(self.spec.workdir):
+            return HealthResult(
+                ok=False, status="offline", detail=f"workdir missing: {self.spec.workdir}"
+            )
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                cli,
+                "--version",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=self._env(),
+                cwd=self.spec.workdir,
+            )
+            stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=10)
+            return HealthResult(ok=True, status="online", detail=stdout.decode().strip())
+        except Exception as e:
+            return HealthResult(ok=False, status="offline", detail=f"version check failed: {e}")
+
+    # ----------------------------------------------------------- process env
+    def _env(self) -> dict[str, str]:
+        env = dict(os.environ)
+        env.update(self.spec.env or {})
+        return env
+
+    # --------------------------------------------------------- flag assembly
+    def _build_args(self, prompt: str, session_id: str | None, fork: bool) -> list[str]:
+        """Assemble the CLI argv from the spec.
+
+        session_id=None, fork=False → new session
+        session_id set, fork=False  → resume
+        session_id set, fork=True   → native fork (requires spec.fork + headless)
+        """
+        # subcommand fork shape (e.g. codex fork <sid> <prompt>) — sid+prompt positional
+        if fork and session_id and self.spec.fork and self.spec.fork.shape == "subcommand":
+            args = [self.spec.fork.subcommand, session_id, prompt]
+            args.extend(self.spec.output_format_flag)
+            args.extend(self.spec.base_flags)
+            return args
+
+        # resume via subcommand (e.g. codex: `exec resume <sid> <prompt> --json`)
+        if session_id and not fork and self.spec.resume_subcommand:
+            args = [self.spec.prompt_flag, self.spec.resume_subcommand, session_id, prompt]
+            args.extend(self.spec.output_format_flag)
+            args.extend(self.spec.base_flags)
+            return args
+
+        # default / flag_overlay shape (e.g. claude -p <p> --resume <sid> --fork-session)
+        if self.spec.prompt_flag:
+            args: list[str] = [self.spec.prompt_flag, prompt]
+        else:
+            # positional prompt (e.g. ccagent "prompt" --output stream-json)
+            args: list[str] = [prompt]
+        args.extend(self.spec.output_format_flag)
+        args.extend(self.spec.base_flags)
+        if session_id and self.spec.resume_flag:
+            args.extend([self.spec.resume_flag, session_id])
+            if fork and self.spec.fork and self.spec.fork.shape == "flag_overlay":
+                args.append(self.spec.fork.flag)
+        return args
+
+    async def _run(
+        self, prompt: str, session_id: str | None, fork: bool, mode_label: str
+    ) -> AsyncIterator[ConnectorEvent]:
+        import logging as _log
+        _dbg = _log.getLogger("baserun_cli._vendored.cli")
+        cli = shutil.which(self.spec.bin) or (
+            self.spec.bin if os.path.exists(self.spec.bin) else self.spec.bin
+        )
+        args = self._build_args(prompt, session_id, fork)
+        _dbg.info("spawning: %s %s (cwd=%s)", cli, " ".join(args[:6]) + ("..." if len(args) > 6 else ""), self.spec.workdir)
+
+        proc = await asyncio.create_subprocess_exec(
+            cli,
+            *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=self._env(),
+            cwd=self.spec.workdir,
+        )
+        _dbg.info("pid=%s started", proc.pid)
+
+        resolved_session_id: str | None = session_id
+        line_count = 0
+        # delta accumulation: consecutive thinking/message deltas are accumulated
+        # and flushed as a complete (non-delta) event when the type changes or EOF.
+        # Ensures JSONL persistence and finalize have complete text even for
+        # agents that only emit token-level deltas (e.g. ccagent).
+        acc: dict[str, str] = {"thinking": "", "message": ""}
+
+        def _flush_acc(ev_type: ConnectorEventType) -> list[ConnectorEvent]:
+            """Flush accumulated text for the given type as a non-delta event."""
+            key = ev_type.value
+            text = acc.get(key, "")
+            if not text:
+                return []
+            acc[key] = ""
+            return [ConnectorEvent(ev_type, {"delta": text, "is_delta": False})]
+
+        try:
+            assert proc.stdout is not None
+            async for raw_line in proc.stdout:
+                line = raw_line.decode(errors="replace").strip()
+                if not line:
+                    continue
+                line_count += 1
+                try:
+                    obj = json.loads(line)
+                except json.JSONDecodeError:
+                    _dbg.debug("pid=%s non-JSON line #%d: %.200s", proc.pid, line_count, line)
+                    continue
+                _dbg.debug("pid=%s JSON line #%d: type=%s", proc.pid, line_count, obj.get("type", "?"))
+                # session id resolution (init line)
+                sid = extract_session_id(self.spec.output_schema, obj)
+                if sid and not resolved_session_id:
+                    resolved_session_id = sid
+                    _dbg.info("pid=%s session_id=%s", proc.pid, sid)
+                    yield ConnectorEvent(
+                        ConnectorEventType.SESSION,
+                        {"agent_session_id": sid, "mode": mode_label},
+                    )
+                # typed events
+                parsed = list(parse_line(self.spec.output_schema, obj))
+                _dbg.debug("pid=%s line #%d → %d event(s): %s", proc.pid, line_count, len(parsed), [e.type.value for e in parsed])
+                for ev in parsed:
+                    # accumulate consecutive deltas; flush on type switch
+                    if ev.type in (ConnectorEventType.THINKING, ConnectorEventType.MESSAGE) and ev.payload.get("is_delta"):
+                        # type switch within deltas (e.g. thinking→message): flush the other type first
+                        other = ConnectorEventType.MESSAGE if ev.type == ConnectorEventType.THINKING else ConnectorEventType.THINKING
+                        for flushed in _flush_acc(other):
+                            yield flushed
+                        acc[ev.type.value] += ev.payload.get("delta", "")
+                        yield ev  # still yield delta for real-time streaming
+                    else:
+                        # non-delta event → flush both accumulators before yielding
+                        for ft in (ConnectorEventType.THINKING, ConnectorEventType.MESSAGE):
+                            for flushed in _flush_acc(ft):
+                                yield flushed
+                        yield ev
+
+            # EOF → flush remaining accumulated text
+            for ft in (ConnectorEventType.THINKING, ConnectorEventType.MESSAGE):
+                for flushed in _flush_acc(ft):
+                    yield flushed
+
+            _dbg.info("pid=%s stdout EOF (total %d lines), waiting for exit...", proc.pid, line_count)
+            await proc.wait()
+            _dbg.info("pid=%s exited returncode=%s", proc.pid, proc.returncode)
+            if proc.returncode not in (0, None):
+                stderr = ""
+                if proc.stderr:
+                    stderr = (await proc.stderr.read()).decode(errors="replace")
+                _dbg.warning("pid=%s stderr: %.500s", proc.pid, stderr)
+                yield ConnectorEvent(
+                    ConnectorEventType.ERROR,
+                    {"message": f"{self.spec.bin} exited {proc.returncode}: {stderr[:500]}"},
+                )
+        except Exception as e:
+            _dbg.exception("pid=%s _run exception", proc.pid)
+            yield ConnectorEvent(ConnectorEventType.ERROR, {"message": str(e)})
+        finally:
+            if proc.returncode is None:
+                _dbg.warning("pid=%s still running, killing", proc.pid)
+                proc.kill()
+                await proc.wait()
+
+    # ----------------------------------------------------------- lifecycle
+    async def new_session(self, prompt: str) -> AsyncIterator[ConnectorEvent]:
+        async for ev in self._run(prompt, session_id=None, fork=False, mode_label="new"):
+            yield ev
+
+    async def resume(
+        self, agent_session_id: str, user_message: str
+    ) -> AsyncIterator[ConnectorEvent]:
+        async for ev in self._run(
+            user_message, session_id=agent_session_id, fork=False, mode_label="resume"
+        ):
+            yield ev
+
+    async def fork(
+        self, agent_session_id: str, user_message: str
+    ) -> AsyncIterator[ConnectorEvent]:
+        if not self.spec.native_fork:
+            raise NotImplementedError(
+                f"{self.spec.bin} has no headless native fork; "
+                "caller must use fallback rebuild"
+            )
+        fs = self.spec.fork
+        assert fs is not None
+        # two_step (codex): step1 create fork → extract id → step2 exec resume
+        if fs.shape == "two_step":
+            async for ev in self._fork_two_step(agent_session_id, user_message, fs):
+                yield ev
+            return
+        # flag_overlay / subcommand: single command
+        async for ev in self._run(
+            user_message, session_id=agent_session_id, fork=True, mode_label="fork"
+        ):
+            yield ev
+
+    async def _fork_two_step(
+        self,
+        agent_session_id: str,
+        user_message: str,
+        fs: "ForkShape",
+    ) -> AsyncIterator[ConnectorEvent]:
+        """Two-step fork: (1) create forked session, (2) exec resume into it.
+
+        Step 1 runs `<bin> fork <sid>` (or fs.fork_cmd) and extracts the new
+        session id from its output via fs.id_pattern. Step 2 builds the resume
+        command from fs.resume_cmd and runs it headless, streaming events.
+        """
+        import shlex
+        import re
+
+        cli = shutil.which(self.spec.bin) or (
+            self.spec.bin if os.path.exists(self.spec.bin) else self.spec.bin
+        )
+
+        # --- step 1: create the fork ---
+        step1_args = shlex.split(fs.fork_cmd.format(sid=agent_session_id))
+        proc = await asyncio.create_subprocess_exec(
+            cli,
+            *step1_args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=self._env(),
+            cwd=self.spec.workdir,
+        )
+        try:
+            out_b, err_b = await asyncio.wait_for(proc.communicate(), timeout=60.0)
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()
+            yield ConnectorEvent(
+                ConnectorEventType.ERROR,
+                {"message": f"fork step1 timed out (TUI may be waiting for input)"},
+            )
+            return
+        combined = (out_b + b"\n" + err_b).decode(errors="replace")
+        m = re.search(fs.id_pattern, combined)
+        if not m:
+            yield ConnectorEvent(
+                ConnectorEventType.ERROR,
+                {"message": f"fork step1 produced no session id: {combined[:300]}"},
+            )
+            return
+        new_session_id = m.group(1)
+
+        # announce the new session id immediately (so the host can persist it)
+        yield ConnectorEvent(
+            ConnectorEventType.SESSION,
+            {"agent_session_id": new_session_id, "mode": "fork"},
+        )
+
+        # --- step 2: exec resume into the new session headless ---
+        # build the resume argv from the template, then append output flags.
+        # shlex-quote the prompt so spaces/special chars survive shlex.split.
+        step2_args = shlex.split(
+            fs.resume_cmd.format(sid=new_session_id, prompt=shlex.quote(user_message))
+        )
+        full_args = step2_args + list(self.spec.output_format_flag) + list(self.spec.base_flags)
+        proc2 = await asyncio.create_subprocess_exec(
+            cli,
+            *full_args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=self._env(),
+            cwd=self.spec.workdir,
+        )
+        try:
+            assert proc2.stdout is not None
+            async for raw_line in proc2.stdout:
+                line = raw_line.decode(errors="replace").strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                for ev in parse_line(self.spec.output_schema, obj):
+                    yield ev
+            await proc2.wait()
+            if proc2.returncode not in (0, None):
+                stderr = ""
+                if proc2.stderr:
+                    stderr = (await proc2.stderr.read()).decode(errors="replace")
+                yield ConnectorEvent(
+                    ConnectorEventType.ERROR,
+                    {"message": f"{self.spec.bin} resume exited {proc2.returncode}: {stderr[:500]}"},
+                )
+        finally:
+            if proc2.returncode is None:
+                proc2.kill()
+                await proc2.wait()