@agent-compose/sdk 0.8.2 → 0.8.3

package/src/runtimes/claude-code.ts

@@ -34,7 +34,7 @@
  *     token-metering gateway's Anthropic passthrough (ADR-0039).
  */
 
-import type { AgentMessage } from "../index.js";
+import type { AgentMessage, AgentMessageTaskNotification } from "../index.js";
 import { createCliAgentRuntime, shellQuote, type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 import { formatError } from "../utils/errors.js";
 
@@ -72,6 +72,140 @@ function toolResultText(content: unknown): string {
   return content == null ? "" : JSON.stringify(content) ?? "";
 }
 
+// ── Task notifications (background-task completion evidence) ────────────────
+//
+// When a background task stops — an async Agent spawn finishing, a
+// background command exiting — claude-code's completion evidence reaches
+// the stream in TWO shapes, and BOTH are mapped here (either one dropped
+// leaves transcripts believing async agents run forever — the incident
+// where spawn cards never left "launched"):
+//
+//   - `system` events with `subtype: "task_notification"` — the ONLY shape
+//     `-p --output-format stream-json` actually emits, verified live on
+//     2.1.212 (the baked E2B version) and 2.1.236, both when the task
+//     finishes MID-turn and on the idle wake (where it precedes a fresh
+//     system/init and a result stamped `origin.kind: "task-notification"`).
+//     Flat JSON: task_id / tool_use_id / status / summary, plus
+//     `usage.{total_tokens,tool_uses,duration_ms}` for agent tasks.
+//   - `<task-notification>` XML blocks as USER-role text — the form the
+//     harness injects into the model's own conversation (and the shape a
+//     resumed turn can surface as a user event). Kept as the second arm so
+//     neither transport ever depends on which side of a resume the
+//     notification lands.
+//
+// Parsed into structure; the internal plumbing either shape carries
+// (output-file paths, resume hints in <note>/<diagnostics>) is deliberately
+// not forwarded — no renderer should ever see it.
+
+const TASK_NOTIFICATION_RE = /<task-notification>([\s\S]*?)<\/task-notification>/g;
+
+const NOTIFICATION_SUMMARY_MAX = 500;
+const NOTIFICATION_REPORT_MAX = 20_000;
+
+/** First `<tag>…</tag>` inside a notification body, or null. */
+function innerTag(body: string, tag: string): string | null {
+  const m = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`).exec(body);
+  const text = m?.[1]?.trim() ?? "";
+  return text.length > 0 ? text : null;
+}
+
+/** The harness entity-escapes text it embeds into notification XML —
+ *  reverse the closed five so the report reads as the agent wrote it. */
+function unescapeEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+const clip = (s: string, max: number): string =>
+  (s.length > max ? `${s.slice(0, max - 1)}…` : s);
+
+function intTag(body: string, tag: string): number | undefined {
+  const raw = innerTag(body, tag);
+  if (!raw) return undefined;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+/** Parse every `<task-notification>` block out of one user-role text blob.
+ *  Pure and tolerant over untrusted harness text: a block without a task id
+ *  is skipped, absent fields stay absent, everything is clamped. Exported
+ *  for tests. */
+export function parseTaskNotifications(
+  text: string, timestamp: string,
+): AgentMessageTaskNotification[] {
+  if (!text.includes("<task-notification>")) return [];
+  const out: AgentMessageTaskNotification[] = [];
+  TASK_NOTIFICATION_RE.lastIndex = 0;
+  for (let m = TASK_NOTIFICATION_RE.exec(text); m !== null; m = TASK_NOTIFICATION_RE.exec(text)) {
+    const body = m[1] ?? "";
+    const taskId = innerTag(body, "task-id");
+    if (!taskId) continue;
+    const toolUseId = innerTag(body, "tool-use-id");
+    const summary = innerTag(body, "summary");
+    const report = innerTag(body, "result");
+    const usageBody = /<usage>([\s\S]*?)<\/usage>/.exec(body)?.[1] ?? "";
+    const tokens = intTag(usageBody, "subagent_tokens");
+    const toolUses = intTag(usageBody, "tool_uses");
+    const durationMs = intTag(usageBody, "duration_ms");
+    out.push({
+      type: "task_notification",
+      taskId: clip(taskId, 128),
+      ...(toolUseId ? { toolUseId: clip(toolUseId, 128) } : {}),
+      status: innerTag(body, "status") ?? "finished",
+      summary: summary ? clip(unescapeEntities(summary.replace(/\s+/g, " ")), NOTIFICATION_SUMMARY_MAX) : "",
+      ...(report ? { report: clip(unescapeEntities(report), NOTIFICATION_REPORT_MAX) } : {}),
+      ...(tokens !== undefined || toolUses !== undefined || durationMs !== undefined
+        ? { usage: {
+            ...(tokens !== undefined ? { tokens } : {}),
+            ...(toolUses !== undefined ? { toolUses } : {}),
+            ...(durationMs !== undefined ? { durationMs } : {}),
+          } }
+        : {}),
+      timestamp,
+    });
+  }
+  return out;
+}
+
+/** One `system`/`task_notification` stream-json event mapped onto the same
+ *  structured message the XML parse produces, or null when the event names
+ *  no task id. Pure and tolerant over untrusted harness JSON: absent fields
+ *  stay absent, everything is clamped; `output_file` (internal plumbing) is
+ *  deliberately not forwarded. Exported for tests. */
+export function parseSystemTaskNotification(
+  p: Record<string, unknown>, timestamp: string,
+): AgentMessageTaskNotification | null {
+  const taskId = typeof p.task_id === "string" && p.task_id.trim().length > 0 ? p.task_id.trim() : null;
+  if (!taskId) return null;
+  const toolUseId = typeof p.tool_use_id === "string" && p.tool_use_id.length > 0 ? p.tool_use_id : null;
+  const summary = typeof p.summary === "string" ? p.summary : "";
+  const nonneg = (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+  const u = (typeof p.usage === "object" && p.usage !== null ? p.usage : {}) as Record<string, unknown>;
+  const tokens = nonneg(u.total_tokens);
+  const toolUses = nonneg(u.tool_uses);
+  const durationMs = nonneg(u.duration_ms);
+  return {
+    type: "task_notification",
+    taskId: clip(taskId, 128),
+    ...(toolUseId ? { toolUseId: clip(toolUseId, 128) } : {}),
+    status: typeof p.status === "string" && p.status.length > 0 ? p.status : "finished",
+    summary: clip(summary.replace(/\s+/g, " ").trim(), NOTIFICATION_SUMMARY_MAX),
+    ...(tokens !== undefined || toolUses !== undefined || durationMs !== undefined
+      ? { usage: {
+          ...(tokens !== undefined ? { tokens } : {}),
+          ...(toolUses !== undefined ? { toolUses } : {}),
+          ...(durationMs !== undefined ? { durationMs } : {}),
+        } }
+      : {}),
+    timestamp,
+  };
+}
+
 /** Claude Code's real reasoning knob is its own `--effort <level>` flag
  *  (low|medium|high|xhigh|max — verified against `claude -p --help`). The
  *  CliReasoningEffort union IS the CLI's vocabulary, so the level rides the
@@ -100,12 +234,30 @@ export const claudeCodeSpec: CliAgentSpec = {
     'sudo cp "$REAL" /usr/local/bin/claude && sudo chmod 0755 /usr/local/bin/claude',
   // Claude reads the prompt from stdin in -p mode.
   promptPayload: (prompt) => prompt,
-  buildCommand: ({ promptPath, sessionId, model, cwd, effort }) => {
+  // Mid-turn stream input (steering): with `--input-format stream-json`,
+  // stdin carries JSONL user messages, and one that arrives WHILE a turn
+  // runs is folded into the running turn at the next tool boundary — the
+  // interactive UI's queued-user-input behaviour, verified live against
+  // claude 2.1.233 (a message injected during a 20s Bash call shaped the
+  // same turn's final reply, and the tool ran undisturbed). Slash-command
+  // expansion and `--resume` both work unchanged in this mode (verified on
+  // the same build). A message that lands after the result would start a
+  // NEW turn in-process, which is why the transport's feeder stops at the
+  // result line instead of forwarding past it.
+  streamInput: {
+    promptLine: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: prompt } }),
+    messageLine: (text) => JSON.stringify({ type: "user", message: { role: "user", content: text } }),
+  },
+  buildCommand: ({ promptPath, sessionId, model, cwd, effort, streamInput }) => {
     const flags = [
       "-p",
       // stream-json is the JSONL event stream; -p requires --verbose with it.
       "--output-format stream-json",
       "--verbose",
+      // Stream-input turns feed stdin as JSONL user messages from the
+      // transport's FIFO (mid-turn injection); plain turns keep the raw
+      // prompt file.
+      ...(streamInput ? ["--input-format stream-json"] : []),
       // Raw API stream events ride along as `stream_event` lines — the
       // text_delta source for progressive rendering (mapEvent below). The
       // complete `assistant` message events still arrive; deltas are
@@ -157,17 +309,29 @@ export const claudeCodeSpec: CliAgentSpec = {
           return [];
         });
       }
-      // User API message: the CLI echoes tool results back as user content.
+      // User API message: the CLI echoes tool results back as user content,
+      // and injects `<task-notification>` blocks (background-task completion
+      // evidence) as user TEXT — parsed into structure, never dropped and
+      // never forwarded raw. Other user text (the echo of the prompt, system
+      // reminders) stays unmapped: it is not agent output.
       case "user": {
-        const message = p.message as { content?: ClaudeContentBlock[] } | undefined;
+        const message = p.message as { content?: ClaudeContentBlock[] | string } | undefined;
+        if (typeof message?.content === "string") {
+          return parseTaskNotifications(message.content, ts);
+        }
         const blocks = Array.isArray(message?.content) ? message.content : [];
-        return blocks.flatMap((b): AgentMessage[] =>
-          b.type === "tool_result"
-            ? [{
-                type: "tool_result", toolUseId: String(b.tool_use_id ?? ""),
-                output: toolResultText(b.content), isError: b.is_error === true, ...parent, timestamp: ts,
-              }]
-            : []);
+        return blocks.flatMap((b): AgentMessage[] => {
+          if (b.type === "tool_result") {
+            return [{
+              type: "tool_result", toolUseId: String(b.tool_use_id ?? ""),
+              output: toolResultText(b.content), isError: b.is_error === true, ...parent, timestamp: ts,
+            }];
+          }
+          if (b.type === "text" && typeof b.text === "string") {
+            return parseTaskNotifications(b.text, ts);
+          }
+          return [];
+        });
       }
       // Raw API stream event (--include-partial-messages): text deltas of
       // the in-progress block map to the live-only `text_delta` kind so a
@@ -234,7 +398,18 @@ export const claudeCodeSpec: CliAgentSpec = {
           timestamp: ts,
         }];
       }
-      // system/init carries the session id (extractSessionId); nothing to map.
+      // System events: init carries the session id (extractSessionId), and
+      // the background-task lane rides here too — `task_notification` is
+      // the completion evidence stream-json actually emits (see the section
+      // header above), so it maps to the structured message BOTH turn
+      // engines persist. Everything else under system (task_started,
+      // task_updated, background_tasks_changed, thinking_tokens) is
+      // lifecycle noise here.
+      case "system": {
+        if (p.subtype !== "task_notification") return [];
+        const notification = parseSystemTaskNotification(p, ts);
+        return notification ? [notification] : [];
+      }
       default:
         return [];
     }

package/src/runtimes/codex.ts

@@ -53,6 +53,54 @@ export function isCodexAdvisoryNoise(text: string): boolean {
   return CODEX_ADVISORY_PATTERNS.some((re) => re.test(text));
 }
 
+// ── Thread-store writer-lock preflight (2026-08-18 prod incident) ────────────
+// codex guards each persisted thread with an OS advisory flock on
+// `$CODEX_HOME/thread-writer-locks/<thread-id>.lock` (codex-rs
+// thread-store/src/local/writer_lock.rs). Two consequences drive this
+// preflight's shape:
+//   - the flock is held exactly as long as the holding PROCESS lives — the
+//     kernel releases it on any death (SIGKILL, VM crash), so a lock that
+//     still blocks is held by a LIVE process, never a stale file;
+//   - codex sweeps unheld (stale) lock FILES itself on store init.
+// The incident: a canceled turn's codex survived its fire-and-forget SIGTERM
+// long enough for the user's next turn to launch `codex exec resume`, which
+// died with `thread-store conflict: thread … already has an active writer`
+// (code -32600). So before a RESUME the launch script:
+//   1. waits (bounded) for a dying previous writer to release the flock —
+//      the canceled predecessor was already TERM'd, it just needs a moment;
+//   2. clears the lock file ONLY under a successfully acquired `flock -n`
+//      (proof the holder is dead) — belt-and-suspenders on top of codex's
+//      own sweep, and the guard against any future file-existence check;
+//   3. NEVER touches a lock whose holder is alive: removing a live-held
+//      lock file would let a second writer flock a fresh inode (two writers
+//      on one rollout), so a still-held lock after the wait is left for
+//      codex to surface as the honest conflict it is.
+// No `flock(1)` on the guest (or no lock file) → the preflight is a no-op.
+
+/** Bounded wait for a dying previous writer: attempts × sleep = 5s, matching
+ *  the teardown's SIGTERM grace (sdk _cli-agent.ts REAP_TERM_WAIT_ATTEMPTS). */
+export const CODEX_LOCK_WAIT_ATTEMPTS = 20;
+export const CODEX_LOCK_WAIT_SECONDS = "0.25";
+
+/** Thread ids are uuid-shaped; anything else skips the preflight entirely so
+ *  hostile config can never become shell injection via the lock path. */
+const CODEX_THREAD_ID_SAFE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** The sh fragment prepended to a resume launch. `waitAttempts` is a test
+ *  seam (the live-holder test must not sleep 5s); production callers take
+ *  the default. Exported for tests. */
+export function codexWriterLockPreflight(
+  threadId: string,
+  waitAttempts: number = CODEX_LOCK_WAIT_ATTEMPTS,
+): string {
+  if (!CODEX_THREAD_ID_SAFE.test(threadId)) return "";
+  return `ac_lk="\${CODEX_HOME:-$HOME/.codex}/thread-writer-locks/${threadId}.lock"; `
+    + `if [ -e "$ac_lk" ] && command -v flock >/dev/null 2>&1; then ac_lki=0; `
+    + `while ! flock -n "$ac_lk" true 2>/dev/null && [ "$ac_lki" -lt ${waitAttempts} ]; do `
+    + `sleep ${CODEX_LOCK_WAIT_SECONDS}; ac_lki=$((ac_lki+1)); done; `
+    + `flock -n "$ac_lk" rm -f -- "$ac_lk" 2>/dev/null || true; fi; `;
+}
+
 /** Exported for the fixture-based parity tests (ADR-0020): the legacy JSONL
  *  `mapEvent` is the golden the ACP normaliser is asserted equal to. Not part
  *  of the public runtime surface — `createCodexRuntime` stays the entry point. */
@@ -60,6 +108,11 @@ export const codexSpec: CliAgentSpec = {
   kind: "codex",
   authEnv: "CODEX_API_KEY",
   bin: "codex",
+  // codex holds a per-thread advisory flock for its writer's whole lifetime
+  // (see the writer-lock preflight above): a live predecessor process blocks
+  // every resume of the same thread, so supersede teardown must KILL it —
+  // never detach it alive (server runner-kill.ts consumes this flag).
+  exclusiveSessionWriter: true,
   // ACP-mode invocation (ADR-0020 increment 1). `codex` has no native `--acp`
   // flag; the adapter (a Rust binary shipped via npm) speaks ACP and drives a
   // compatible bundled `@openai/codex`. The runner attempts this first and
@@ -103,12 +156,16 @@ export const codexSpec: CliAgentSpec = {
     // died. `cd` sets the cwd identically for both paths; promptPath is
     // absolute (/tmp/…), so the `< prompt` redirect survives the cd.
     const cd = cwd ? `cd ${shellQuote(cwd)} && ` : "";
+    // Resume-only launch preflight: self-heal a released-or-dying writer
+    // lock before `codex exec resume` (see codexWriterLockPreflight). A
+    // fresh turn mints a new thread id — no lock can exist for it yet.
+    const preflight = sessionId ? codexWriterLockPreflight(sessionId) : "";
     // Fresh turn: `codex exec <flags> - < prompt`. Continue a thread:
     // `codex exec resume <id> <flags> - < prompt`. (`-` = read prompt from stdin.)
     const exec = sessionId
       ? `codex exec resume ${shellQuote(sessionId)} ${flags}`
       : `codex exec ${flags}`;
-    return `${cd}${exec} - < ${shellQuote(promptPath)}`;
+    return `${preflight}${cd}${exec} - < ${shellQuote(promptPath)}`;
   },
   extractSessionId: (p) =>
     p.type === "thread.started" && typeof p.thread_id === "string" ? p.thread_id : undefined,

package/src/sandbox/providers/local.ts

@@ -5,6 +5,16 @@
 import { promises as fs } from "node:fs";
 import { dirname } from "node:path";
 import { spawn } from "node:child_process";
+/** The two listener registrations we need, declared LOCALLY.
+ *  `ChildProcess` inherits `.on` from EventEmitter, but when a tree ends up
+ *  with more than one @types/node the inheritance link breaks and `.on`
+ *  disappears — which resolution you get depends on install layout, so this
+ *  typechecked locally and failed CI three times. Referencing no node types
+ *  at all is the only version-proof shape. */
+type ProcListeners = {
+  on(event: "error", cb: (err: Error) => void): unknown;
+  on(event: "close", cb: (code: number | null) => void): unknown;
+};
 import { Readable, Writable } from "node:stream";
 import type { SandboxProvider } from "../../types/sandbox.js";
 
@@ -36,8 +46,9 @@ export function makeLocalSandboxProvider(): SandboxProvider {
           proc.stderr?.setEncoding("utf8");
           proc.stdout?.on("data", (chunk: string) => { stdout += chunk; opts?.onStdout?.(chunk); });
           proc.stderr?.on("data", (chunk: string) => { stderr += chunk; opts?.onStderr?.(chunk); });
-          proc.on("error", reject);
-          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
+          const ev = proc as unknown as ProcListeners;
+          ev.on("error", reject);
+          ev.on("close", (code: number | null) => resolve({ exitCode: code ?? 0, stdout, stderr }));
         });
       },
       // Duplex spawn — the in-VM `child_process` pipe the ACP client needs.
@@ -67,8 +78,9 @@ export function makeLocalSandboxProvider(): SandboxProvider {
         proc.stderr.on("data", (chunk: string) => { stderr += chunk; });
 
         const exited = new Promise<{ exitCode: number; stderr: string }>((resolve, reject) => {
-          proc.on("error", reject);
-          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stderr }));
+          const ev = proc as unknown as ProcListeners;
+          ev.on("error", reject);
+          ev.on("close", (code: number | null) => resolve({ exitCode: code ?? 0, stderr }));
         });
 
         return {