@agent-compose/sdk 0.7.0 → 0.8.1

package/src/runtimes/_cli-agent.ts

@@ -24,7 +24,7 @@
  * values set via `agentc secrets set` are visible to the CLI.
  */
 
-import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";
+import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxCommandResult, SandboxProvider, ToolCallGateResult } from "../index.js";
 import { defineRuntime } from "../types/runtime.js";
 import { AsyncQueue } from "../agent/async-queue.js";
 import { formatError } from "../utils/errors.js";
@@ -34,6 +34,10 @@ import type { ProcessorContext, ToolCall } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
 import { AcpClientPeer, ACP_PROTOCOL_VERSION } from "./_acp-client.js";
 import { isPauseSignal, boundProcessorPause } from "../pause/pause-core.js";
+import {
+  JSONL_GUARD_LINE_CAP_BYTES, JSONL_GUARD_KEEP_BYTES,
+  jsonlGuardScript, wrapJsonlCommand,
+} from "./_jsonl-guard.js";
 
 function now(): string { return new Date().toISOString(); }
 
@@ -42,6 +46,28 @@ export function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/** Monotonic discriminator for prompt-file names within this process. */
+let promptFileCounter = 0;
+
+/**
+ * A UNIQUE per-turn prompt path. Uniqueness is load-bearing, not cosmetic:
+ * E2B's envd cannot overwrite an existing non-root file in /tmp — it opens
+ * with O_CREAT as root (then chowns to the user), and the sandbox kernel's
+ * `fs.protected_regular` policy denies O_CREAT opens by a non-owner of an
+ * existing file in a sticky world-writable directory — so ANY reused path
+ * fails with "error opening file: … permission denied" on every turn after
+ * the first (same boot or across suspend/resume; reproduced against e2b
+ * 2.30.5). Cloud sessions construct a fresh runner per turn, so an
+ * iteration counter alone reuses `…-0.in` per conversation — the exact
+ * production failure. The timestamp+counter+random suffix is collision-proof
+ * across runner instances AND concurrent turns in one sandbox; the readable
+ * prefix (kind/agent/iteration) stays for debugging.
+ */
+export function uniquePromptPath(kind: string, agentId: string, iteration: number): string {
+  const unique = `${Date.now().toString(36)}-${(promptFileCounter++).toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  return `/tmp/ac-${kind}-${agentId}-${iteration}-${unique}.in`;
+}
+
 /** Internal sentinel yielded by `sendMessageAcp` to signal the version-check
  *  fallback: the ACP handshake didn't negotiate version 1, so `sendMessage`
  *  must drive the legacy JSONL path for this (and every later) turn. Not an
@@ -93,6 +119,16 @@ async function withHandshakeTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
   }
 }
 
+/** Reasoning-effort level a CLI turn may carry (T2 session effort) — the
+ *  UNION of what the effort-capable CLIs accept. The per-CLI mapping lives in
+ *  each spec's `buildCommand` — Claude Code takes its own `--effort` flag
+ *  (all five levels), codex takes `-c model_reasoning_effort=<level>`
+ *  (low|medium|high|xhigh — no "max"; the spec clamps it). Specs without a
+ *  real knob (opencode/droid/cursor) never receive one: the server hides +
+ *  rejects effort for those runtimes, and rejects levels a runtime lacks
+ *  (sessionEffortLockError). */
+export type CliReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max";
+
 /** Per-CLI behaviour. The base owns the lifecycle (init/done/error) and the
  *  transport (spawn + JSONL parse); a spec owns the CLI-specific bits. */
 export interface CliAgentSpec {
@@ -117,8 +153,10 @@ export interface CliAgentSpec {
    *  JSONL user message for a `--stream-json-input` CLI (amp). */
   promptPayload(prompt: string): string;
   /** Build the one-shot shell command for a turn. `promptPath` is a file in the
-   *  sandbox holding `promptPayload(prompt)`; `sessionId` continues a thread. */
-  buildCommand(args: { promptPath: string; sessionId?: string; model?: string; cwd?: string }): string;
+   *  sandbox holding `promptPayload(prompt)`; `sessionId` continues a thread.
+   *  `effort` is present only when the caller configured a reasoning effort
+   *  AND the spec has a real knob for it (see `CliReasoningEffort`). */
+  buildCommand(args: { promptPath: string; sessionId?: string; model?: string; cwd?: string; effort?: CliReasoningEffort }): string;
   /** Map one parsed JSONL stdout event to `AgentMessage`s. The base emits
    *  `init`/`done`/`error` lifecycle itself, so a spec maps only content +
    *  usage (text / thinking / tool_use / tool_result / usage).
@@ -208,6 +246,7 @@ export class CliAgentRunner implements ModelExecutionContract {
     private readonly options: RuntimeOptions,
     private readonly spec: CliAgentSpec,
     private readonly configModel?: string,
+    private readonly configEffort?: CliReasoningEffort,
   ) {
     this.kind = spec.kind;
   }
@@ -529,10 +568,29 @@ export class CliAgentRunner implements ModelExecutionContract {
 
   /**
    * Legacy JSONL transport (the version-mismatch fallback, ADR-0020 increment
-   * 5 retires it). Unchanged behaviour: write the prompt to a file, run the
+   * 5 retires it) — and the ONLY transport on server→sandbox providers (no
+   * `spawnDuplex`, so ACP never engages). Write the prompt to a file, run the
    * one-shot command, line-buffer stdout, `mapEvent` each parsed line, and cap
    * with the runner-synthesised `done`. Does NOT re-yield `init` (the caller
    * already did).
+   *
+   * Deadline + termination semantics (both load-bearing on the server→E2B
+   * cloud-session path):
+   *   - `timeoutMs: 0` disables the PROVIDER's own command deadline. E2B's
+   *     `CommandStartOpts` defaults to 60s — a fraction of a real coding
+   *     turn — and connect-web normalises `<= 0` to "no deadline" (the same
+   *     idiom `launchStep` uses for the hours-long step runner). The local
+   *     and Vercel providers already treat 0/absent as "no deadline". The
+   *     turn's deadline belongs to the CALLER: the abort signal here, the
+   *     bridge waiter's idle/absolute caps, or the in-VM step deadline.
+   *   - Abort and early generator exit KILL the in-sandbox CLI process via
+   *     the provider's kill-capable background handle (`runBackground` —
+   *     present on E2B, the provider every server-driven turn runs on), so a
+   *     cancelled/timed-out/superseded turn can never leave an orphan agent
+   *     mutating the working tree. Providers without `runBackground` (local
+   *     child_process, Vercel) fall back to `commands.run`: no kill handle,
+   *     abort only stops consumption — the pre-ACP behaviour of the in-VM
+   *     JSONL fallback, bounded by the sandbox VM's own lifetime.
    */
   private async *sendMessageJsonl(opts: {
     prompt: string;
@@ -543,18 +601,43 @@ export class CliAgentRunner implements ModelExecutionContract {
     let sessionId = opts.sessionId;
     let sawError = false;
     try {
+      if (opts.signal?.aborted) return;
       // Provision the CLI before the first turn (no-op when it's already
       // present, e.g. booting from a "reuse" snapshot). A failure here surfaces
       // as an `error` AgentMessage via the catch below.
       await this.ensureInstalled();
 
-      const promptPath = `/tmp/ac-${this.spec.kind}-${this.options.agentId ?? "agent"}-${opts.iteration ?? 0}.in`;
+      const promptPath = uniquePromptPath(this.spec.kind, this.options.agentId ?? "agent", opts.iteration ?? 0);
       await this.sandbox.files.write(promptPath, this.spec.promptPayload(opts.prompt));
       const cmd = this.spec.buildCommand({
         promptPath,
         sessionId: opts.sessionId,
         model: this.model,
         cwd: this.options.cwd,
+        effort: this.configEffort,
+      });
+
+      // Frame guard (see _jsonl-guard.ts): the CLI's stdout is piped through
+      // an in-sandbox node filter that caps any oversized JSONL line BEFORE
+      // it reaches the server→sandbox command stream — a single multi-hundred-
+      // KB tool_result line on E2B's connect-web stream dies as `13: [internal]
+      // protocol error: received unsupported compressed output`, killing the
+      // turn and recycling the VM. Truncated payloads carry an explicit
+      // elision marker (the full content stays durable in the sandbox); the
+      // CLI's real exit code rides a per-turn random sentinel line so the
+      // pipe never masks it. The script travels over `files.write` — envd's
+      // HTTP API, immune to the connect-web fault — and the wrapper itself
+      // falls back to the bare command when the sandbox has no `node`.
+      // Derived from promptPath so it inherits the collision-proof uniqueness
+      // (E2B's envd cannot overwrite an existing /tmp file — see
+      // uniquePromptPath) and the same opportunistic cleanup below.
+      const guardPath = `${promptPath}.guard.js`;
+      const sentinel = `__AC_JSONL_EXIT_${Math.random().toString(36).slice(2, 10)}__`;
+      await this.sandbox.files.write(guardPath, jsonlGuardScript());
+      const guardedCmd = wrapJsonlCommand({
+        cmd, guardPath, sentinel,
+        maxBytes: JSONL_GUARD_LINE_CAP_BYTES,
+        keepBytes: JSONL_GUARD_KEEP_BYTES,
       });
 
       // Bridge the streaming stdout callback into an async-iterable of complete
@@ -570,48 +653,90 @@ export class CliAgentRunner implements ModelExecutionContract {
           if (line) lines.push(line);
         }
       };
-
-      // `commands.run` resolves when the process exits. Kick it off (don't await
-      // yet); flush the trailing buffer + close the queue on completion so the
-      // for-await below drains and we can read the exit code.
-      const runPromise = this.sandbox.commands.run(cmd, {
+      const runOpts = {
         ...(this.options.cwd ? { cwd: this.options.cwd } : {}),
         onStdout,
-      }).then(
-        (res) => { const tail = buf.trim(); if (tail) lines.push(tail); lines.close(); return res; },
-        (err) => { lines.close(); throw err; },
-      );
-
-      for await (const line of lines) {
-        let parsed: Record<string, unknown>;
-        try {
-          parsed = JSON.parse(line) as Record<string, unknown>;
-        } catch {
-          continue; // skip any non-JSON noise that lands on stdout
-        }
-        const sid = this.spec.extractSessionId(parsed);
-        if (sid) sessionId = sid;
-        for (const msg of this.spec.mapEvent(parsed)) {
-          if (msg.type === "error") sawError = true;
-          yield msg;
-        }
+        timeoutMs: 0,   // no provider deadline — see the doc comment above
+      };
+
+      // The command resolves when the process exits. Kick it off (don't await
+      // yet); flush the trailing buffer + close the queue on completion so the
+      // for-await below drains and we can read the exit code. Prefer the
+      // kill-capable background handle so abort/early-exit can terminate the
+      // process itself, not just stop reading its stream.
+      let exited = false;
+      const settle = (res: SandboxCommandResult): SandboxCommandResult => {
+        exited = true;
+        const tail = buf.trim();
+        if (tail) lines.push(tail);
+        lines.close();
+        return res;
+      };
+      const fail = (err: unknown): never => { exited = true; lines.close(); throw err; };
+      let kill: (() => Promise<void>) | undefined;
+      let runPromise: Promise<SandboxCommandResult>;
+      if (this.sandbox.commands.runBackground) {
+        const handle = await this.sandbox.commands.runBackground(guardedCmd, runOpts);
+        kill = () => handle.kill();
+        runPromise = handle.wait().then(settle, fail);
+      } else {
+        runPromise = this.sandbox.commands.run(guardedCmd, runOpts).then(settle, fail);
       }
+      // An early generator exit stops awaiting runPromise — keep its rejection
+      // observed so an aborted turn can never surface an unhandled rejection.
+      runPromise.catch(() => { /* observed via `await runPromise` when consumed */ });
+
+      const reap = () => { if (!exited) void kill?.().catch(() => { /* already gone */ }); };
+      if (opts.signal) {
+        if (opts.signal.aborted) reap();
+        else opts.signal.addEventListener("abort", reap, { once: true });
+      }
+      try {
+        for await (const line of lines) {
+          let parsed: Record<string, unknown>;
+          try {
+            parsed = JSON.parse(line) as Record<string, unknown>;
+          } catch {
+            continue; // skip any non-JSON noise that lands on stdout
+          }
+          const sid = this.spec.extractSessionId(parsed);
+          if (sid) sessionId = sid;
+          for (const msg of this.spec.mapEvent(parsed)) {
+            if (msg.type === "error") sawError = true;
+            yield msg;
+          }
+        }
 
-      const res = await runPromise;
-      if (res.exitCode !== 0 && !sawError) {
-        const tail = (res.stderr ?? "").slice(-2000);
-        yield { type: "error", text: `${this.spec.kind} exited with code ${res.exitCode}${tail ? `: ${tail}` : ""}`, timestamp: now() };
-        return;
+        const res = await runPromise;
+        if (res.exitCode !== 0 && !sawError) {
+          const tail = (res.stderr ?? "").slice(-2000);
+          yield { type: "error", text: `${this.spec.kind} exited with code ${res.exitCode}${tail ? `: ${tail}` : ""}`, timestamp: now() };
+          return;
+        }
+        if (!sawError) yield { type: "done", sessionId: sessionId ?? "", timestamp: now() };
+      } finally {
+        // Runs on completion AND on early generator exit (the caller broke
+        // out of its for-await: abort, turn closed under the executor,
+        // supersede). `reap` is a no-op once the process has exited.
+        opts.signal?.removeEventListener("abort", reap);
+        reap();
+        // Opportunistic prompt-file + guard-script cleanup: paths are never
+        // reused (see uniquePromptPath), so this is hygiene, not correctness —
+        // fire and forget, and a dead sandbox / failed rm is fine. The shell
+        // holds an open fd on the redirect, so unlinking under a still-exiting
+        // CLI is harmless.
+        void this.sandbox.commands.run(
+          `rm -f ${shellQuote(promptPath)} ${shellQuote(guardPath)}`, { timeoutMs: 10_000 })
+          .catch(() => { /* best-effort */ });
       }
-      if (!sawError) yield { type: "done", sessionId: sessionId ?? "", timestamp: now() };
     } catch (err) {
       yield { type: "error", text: formatError(err), timestamp: now() };
     }
   }
 }
 
-export function createCliAgentRuntime(spec: CliAgentSpec, configModel?: string) {
+export function createCliAgentRuntime(spec: CliAgentSpec, configModel?: string, configEffort?: CliReasoningEffort) {
   return defineRuntime({
-    create: (sandbox, opts) => new CliAgentRunner(sandbox, opts, spec, configModel),
+    create: (sandbox, opts) => new CliAgentRunner(sandbox, opts, spec, configModel, configEffort),
   });
 }

package/src/runtimes/_jsonl-guard.ts

@@ -0,0 +1,219 @@
+/**
+ * JSONL frame guard — keeps oversized lines OFF the server→sandbox command
+ * stream.
+ *
+ * The live failure this exists for: a cloud session's turn stream rides
+ * `sandbox.commands.run` over E2B's connect-web gRPC command stream, and that
+ * transport dies at the wire on large payloads — connect-web throws
+ * `13: [internal] protocol error: received unsupported compressed output`
+ * the moment an envelope arrives with the compressed flag set
+ * (@connectrpc/connect-web connect-transport.js), which is what E2B's edge
+ * does to it on big frames. A single `claude` stream-json event echoing a
+ * whole Read file (hundreds of KB on ONE JSONL line) is exactly such a
+ * payload: the stream faults mid-turn, the platform classifies it as a
+ * protocol transport fault (server cloud-executor.ts), recycles the VM, and
+ * the turn's work is lost.
+ *
+ * The structural fix: the full content is already durable INSIDE the sandbox
+ * (the file on disk, the CLI's own session transcript), so the wire never
+ * needs it. A tiny dependency-free node filter runs in-sandbox, piped after
+ * the CLI, and rewrites any oversized JSONL line before it can reach the
+ * vulnerable stream: long strings inside the event are truncated with an
+ * EXPLICIT elision marker (a silent cut is how models and humans end up
+ * trusting hallucinated file contents), and a line that cannot be capped
+ * structurally is hard-truncated so the stream survives at the cost of that
+ * one event. The prompt travels the other direction over `files.write` —
+ * E2B's envd HTTP API, a different transport documented immune to this
+ * failure (see the `files.read` comment in sandbox/providers/e2b.ts) — and
+ * the guard script itself is delivered the same immune way.
+ *
+ * Exit codes: piping would normally replace the CLI's exit code with the
+ * filter's, so the wrapper prints a per-turn random sentinel line carrying
+ * `$?` after the CLI exits and the filter re-raises it as its own exit code.
+ * EOF without a sentinel means the producer died abnormally (killed
+ * mid-pipe) — the filter exits JSONL_GUARD_NO_SENTINEL_EXIT so a crashed CLI
+ * can never masquerade as a clean turn.
+ *
+ * `capJsonlLine` is deliberately SELF-CONTAINED (no imports, no captured
+ * helpers): `jsonlGuardScript()` embeds it via `Function.prototype.toString`
+ * so the exact logic the unit tests pin is the logic that runs in-sandbox —
+ * one implementation, two call sites.
+ */
+
+/** Trigger threshold: a JSONL line at or under this many bytes passes
+ *  through byte-identical; over it, the guard rewrites. Chosen well under
+ *  whatever E2B's edge chokes on (the observed kills were multi-hundred-KB
+ *  single lines) while comfortably above any sane tool result. */
+export const JSONL_GUARD_LINE_CAP_BYTES =
+  Number(process.env.AC_JSONL_LINE_CAP_BYTES) || 131_072;
+
+/** How many bytes of an oversized string survive elision (the head — tool
+ *  output fronts-loads the signal: file starts, command output starts). */
+export const JSONL_GUARD_KEEP_BYTES =
+  Number(process.env.AC_JSONL_KEEP_BYTES) || 32_768;
+
+/** The guard's exit code when its stdin hit EOF WITHOUT the exit sentinel:
+ *  the producer pipeline died abnormally (killed / crashed sh), so the turn
+ *  must surface as an error, never a clean done. */
+export const JSONL_GUARD_NO_SENTINEL_EXIT = 121;
+
+/** Stable prefix of the elision marker appended to every truncated string.
+ *  Exported so consumers/tests can detect an elided payload; a unit test
+ *  pins that `capJsonlLine`'s embedded copy matches this constant. */
+export const JSONL_ELISION_MARKER_PREFIX = "[agent-compose: PAYLOAD ELIDED IN TRANSIT";
+
+/**
+ * Cap one JSONL line to at most `maxBytes` bytes.
+ *
+ *  - At or under `maxBytes`: returned byte-identical (never re-serialized).
+ *  - Over it and parseable as a JSON object/array: every string longer than
+ *    `keepBytes` is truncated to its first `keepBytes` bytes plus an honest
+ *    elision marker telling the reader the full content still exists in the
+ *    sandbox and how to get it. If the result still exceeds `maxBytes`
+ *    (many big strings), the per-string budget shrinks 8× and then 64× before
+ *    giving up.
+ *  - Unparseable, or uncappable even at the smallest budget: hard byte
+ *    truncation to `maxBytes`. The line stops being valid JSON, so the
+ *    consumer's parse skips it — one event lost, stream alive (strictly
+ *    better than the whole turn dying).
+ *
+ * SELF-CONTAINED by contract: no imports, no outer-scope references except
+ * globals (`Buffer`, `JSON`) — `jsonlGuardScript()` ships `this.toString()`
+ * into the sandbox. Keep it that way.
+ */
+export function capJsonlLine(line: string, maxBytes: number, keepBytes: number): string {
+  if (Buffer.byteLength(line, "utf8") <= maxBytes) return line;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    parsed = undefined;
+  }
+  if (parsed !== null && typeof parsed === "object") {
+    const truncate = (value: string, budget: number): string => {
+      const bytes = Buffer.byteLength(value, "utf8");
+      if (bytes <= budget) return value;
+      let head = Buffer.from(value, "utf8").subarray(0, budget).toString("utf8");
+      // A mid-codepoint cut decodes a trailing U+FFFD — drop it.
+      while (head.endsWith("�")) head = head.slice(0, -1);
+      // At tiny budgets (an event stuffed with MANY big strings) the full
+      // guidance would dwarf the kept content and defeat the shrink loop —
+      // keep the marker prefix (consumers key on it) but drop the prose.
+      if (budget < 2048) {
+        return head + "\n[agent-compose: PAYLOAD ELIDED IN TRANSIT - kept first "
+          + budget + " of " + bytes + " bytes; full content remains in the sandbox]";
+      }
+      return head
+        + "\n\n[agent-compose: PAYLOAD ELIDED IN TRANSIT - this content was " + bytes
+        + " bytes; only the first " + budget + " bytes are shown. It was cut to protect the"
+        + " session's transport, NOT because the source is short: the full content still exists"
+        + " inside this sandbox (the file on disk / the command's output). Do not guess the"
+        + " elided part - re-read the source file, or re-run the command with narrower output"
+        + " (head, tail, grep, offset+limit), to see it.]";
+    };
+    const walk = (node: unknown, budget: number): unknown => {
+      if (typeof node === "string") return truncate(node, budget);
+      if (Array.isArray(node)) return node.map((item) => walk(item, budget));
+      if (node !== null && typeof node === "object") {
+        const out: Record<string, unknown> = {};
+        for (const key of Object.keys(node as Record<string, unknown>)) {
+          out[key] = walk((node as Record<string, unknown>)[key], budget);
+        }
+        return out;
+      }
+      return node;
+    };
+    for (const shrink of [1, 8, 64]) {
+      const budget = Math.max(64, Math.floor(keepBytes / shrink));
+      try {
+        const capped = JSON.stringify(walk(parsed, budget));
+        if (typeof capped === "string" && Buffer.byteLength(capped, "utf8") <= maxBytes) {
+          return capped;
+        }
+      } catch {
+        break; // structural failure — fall through to the raw truncate
+      }
+    }
+  }
+  let raw = Buffer.from(line, "utf8").subarray(0, maxBytes).toString("utf8");
+  while (raw.endsWith("�")) raw = raw.slice(0, -1);
+  return raw;
+}
+
+/**
+ * The in-sandbox filter's source: a dependency-free node script that
+ * line-buffers stdin, re-emits every line through `capJsonlLine`, and turns
+ * the exit sentinel into its own exit code.
+ *
+ *   node <script> <sentinel> <maxBytes> <keepBytes>
+ */
+export function jsonlGuardScript(): string {
+  return [
+    "'use strict';",
+    `const capJsonlLine = ${capJsonlLine.toString()};`,
+    `const NO_SENTINEL_EXIT = ${JSONL_GUARD_NO_SENTINEL_EXIT};`,
+    "const sentinel = process.argv[2];",
+    "const maxBytes = Number(process.argv[3]);",
+    "const keepBytes = Number(process.argv[4]);",
+    "let sawSentinel = false;",
+    "let buf = '';",
+    "// Downstream (the command-stream consumer) going away must never crash",
+    "// the pipe with EPIPE noise — the producer is being killed anyway.",
+    "process.stdout.on('error', () => process.exit(0));",
+    "function handle(line) {",
+    "  const t = line.trim();",
+    "  if (sentinel && t.startsWith(sentinel)) {",
+    "    const code = Number(t.slice(sentinel.length).trim());",
+    "    process.exitCode = Number.isFinite(code) ? code : 0;",
+    "    sawSentinel = true;",
+    "    return;",
+    "  }",
+    "  process.stdout.write(capJsonlLine(line, maxBytes, keepBytes) + '\\n');",
+    "}",
+    "process.stdin.setEncoding('utf8');",
+    "process.stdin.on('data', (d) => {",
+    "  buf += d;",
+    "  let nl;",
+    "  while ((nl = buf.indexOf('\\n')) >= 0) {",
+    "    const line = buf.slice(0, nl);",
+    "    buf = buf.slice(nl + 1);",
+    "    if (line.length > 0) handle(line);",
+    "  }",
+    "});",
+    "process.stdin.on('end', () => {",
+    "  if (buf.trim().length > 0) handle(buf);",
+    "  if (!sawSentinel) process.exitCode = NO_SENTINEL_EXIT;",
+    "});",
+  ].join("\n");
+}
+
+/** Single-quote a value for a `sh -c` command line (local copy — this module
+ *  must not import from _cli-agent.ts, which imports it). */
+function quote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Wrap a turn command so its stdout crosses the command stream through the
+ * guard. Self-deciding in-sandbox: when `node` is absent (a bare sandbox a
+ * self-provisioned CLI runs on), the command runs unguarded — the pre-guard
+ * status quo — instead of failing every turn.
+ *
+ * The command runs in a SUBSHELL so a `$?`-carrying sentinel line always
+ * prints after it exits, however it exits (a brace group would let a shell
+ * `exit` skip the printf). stderr stays un-piped — the provider's stderr
+ * accumulation is unchanged.
+ */
+export function wrapJsonlCommand(args: {
+  cmd: string;
+  guardPath: string;
+  sentinel: string;
+  maxBytes: number;
+  keepBytes: number;
+}): string {
+  const { cmd, guardPath, sentinel, maxBytes, keepBytes } = args;
+  return `if command -v node >/dev/null 2>&1; then `
+    + `{ ( ${cmd} ); printf '\\n%s %s\\n' ${quote(sentinel)} "$?"; } `
+    + `| node ${quote(guardPath)} ${quote(sentinel)} ${maxBytes} ${keepBytes}; `
+    + `else ${cmd}; fi`;
+}