@agent-compose/sdk 0.8.4 → 0.8.5

package/src/runtimes/claude-code.ts

@@ -34,7 +34,10 @@
  *     token-metering gateway's Anthropic passthrough (ADR-0039).
  */
 
-import type { AgentMessage, AgentMessageTaskNotification } from "../index.js";
+import type {
+  AgentMessage, AgentMessageCompaction, AgentMessageTaskNotification, AgentMessageTaskProgress,
+  WorkflowProgressEntry,
+} from "../index.js";
 import { createCliAgentRuntime, shellQuote, type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 import { formatError } from "../utils/errors.js";
 
@@ -171,6 +174,37 @@ export function parseTaskNotifications(
   return out;
 }
 
+/** Clamp for a steer delivered into a child's thread — same ceiling as a
+ *  notification report: plenty for any real addendum, bounded against a
+ *  runaway blob. */
+const SUBAGENT_USER_MESSAGE_MAX = 20_000;
+
+/** One user-role TEXT blob from the stream, mapped with sidechain awareness.
+ *  Task-notification blocks parse into structure wherever they appear (their
+ *  arrival side is resume-dependent — see the transport notes above). What
+ *  remains is then split by attribution: TOP-LEVEL text (no parent id) stays
+ *  unmapped exactly as before — prompt echoes and system reminders are not
+ *  agent output. SIDECHAIN text (parent id present) is a message landing in
+ *  a child subagent's thread — a delivered SendMessage steer — and forwards
+ *  as `subagent_user_message`, except harness plumbing (`<system-reminder>`
+ *  wrappers the CLI injects into child threads), which no renderer should
+ *  see. Exported for tests. */
+export function sidechainAwareUserText(
+  text: string, parentToolUseId: string | undefined, timestamp: string,
+): AgentMessage[] {
+  const notifications = parseTaskNotifications(text, timestamp);
+  if (notifications.length > 0) return notifications;
+  if (!parentToolUseId) return [];
+  const trimmed = text.trim();
+  if (trimmed.length === 0 || trimmed.startsWith("<system-reminder>")) return [];
+  return [{
+    type: "subagent_user_message",
+    text: clip(trimmed, SUBAGENT_USER_MESSAGE_MAX),
+    parentToolUseId,
+    timestamp,
+  }];
+}
+
 /** 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
@@ -206,6 +240,175 @@ export function parseSystemTaskNotification(
   };
 }
 
+// ── Task progress (live background-workflow evidence) ───────────────────────
+//
+// While a harness Workflow (the CLI's in-harness dynamic-workflow tool)
+// runs in the background, stream-json emits `system`/`task_progress`
+// events carrying the workflow's CUMULATIVE `workflow_progress` array —
+// verified live on 2.1.241 (`-p --output-format stream-json`): the array
+// re-sends on every agent state change immediately and on a ~10s heartbeat
+// otherwise, each `workflow_agent` entry updated in place (label,
+// phase, model, state, tokens, toolCalls, durationMs). This is the ONLY
+// per-agent evidence the wire ever carries — the completion notification
+// reports aggregates only — so dropping it leaves workflow cards blind.
+// Preview text (promptPreview / resultPreview) is internal plumbing and is
+// not forwarded, same rule as task notifications.
+
+const PROGRESS_PHASES_MAX = 32;
+const PROGRESS_AGENTS_MAX = 128;
+const PROGRESS_LABEL_MAX = 200;
+const PROGRESS_ERROR_MAX = 500;
+
+const AGENT_STATES: ReadonlySet<string> = new Set(["start", "progress", "done", "error"]);
+
+/** One `system`/`task_progress` event mapped onto the structured progress
+ *  message, or null only when it names no task. Workflow tasks carry the
+ *  cumulative `workflow_progress` entries; a plain background Agent-task
+ *  heartbeat (no workflow entries — verified live on 2.1.241, ~10s cadence
+ *  while the task runs) forwards with `workflow: []` so the platform can
+ *  DECLARE the running task as session background work (the delegation-
+ *  survives-the-human contract: parks, user interrupts, and supersedes all
+ *  read the declared-children registry). Completion evidence still rides
+ *  `task_notification`. Pure and tolerant over untrusted harness JSON:
+ *  malformed entries are skipped, everything is clamped (phases keep the
+ *  FIRST 32 — they are seeded up front; agents keep the LAST 128 — late
+ *  spawns matter more than a long-settled prefix). Exported for tests. */
+export function parseSystemTaskProgress(
+  p: Record<string, unknown>, timestamp: string,
+): AgentMessageTaskProgress | null {
+  const taskId = typeof p.task_id === "string" && p.task_id.trim().length > 0 ? p.task_id.trim() : null;
+  if (!taskId) return null;
+  const raw = Array.isArray(p.workflow_progress) ? p.workflow_progress : [];
+  const nonneg = (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+  const str = (v: unknown, max: number): string | undefined =>
+    typeof v === "string" && v.length > 0 ? clip(v, max) : undefined;
+  const phases: WorkflowProgressEntry[] = [];
+  const agents: WorkflowProgressEntry[] = [];
+  for (const e of raw) {
+    if (typeof e !== "object" || e === null) continue;
+    const o = e as Record<string, unknown>;
+    const index = nonneg(o.index);
+    if (index === undefined) continue;
+    if (o.type === "workflow_phase") {
+      const title = str(o.title, PROGRESS_LABEL_MAX);
+      if (title && phases.length < PROGRESS_PHASES_MAX) phases.push({ kind: "phase", index, title });
+      continue;
+    }
+    if (o.type !== "workflow_agent") continue;
+    const label = str(o.label, PROGRESS_LABEL_MAX);
+    const state = typeof o.state === "string" && AGENT_STATES.has(o.state) ? o.state as "start" | "progress" | "done" | "error" : null;
+    if (!label || !state) continue;
+    agents.push({
+      kind: "agent", index, label, state,
+      ...(nonneg(o.phaseIndex) !== undefined ? { phaseIndex: nonneg(o.phaseIndex) } : {}),
+      ...(str(o.phaseTitle, PROGRESS_LABEL_MAX) ? { phaseTitle: str(o.phaseTitle, PROGRESS_LABEL_MAX) } : {}),
+      ...(str(o.model, 100) ? { model: str(o.model, 100) } : {}),
+      ...(str(o.agentId, 128) ? { agentId: str(o.agentId, 128) } : {}),
+      ...(nonneg(o.tokens) !== undefined ? { tokens: nonneg(o.tokens) } : {}),
+      ...(nonneg(o.toolCalls) !== undefined ? { toolCalls: nonneg(o.toolCalls) } : {}),
+      ...(nonneg(o.durationMs) !== undefined ? { durationMs: nonneg(o.durationMs) } : {}),
+      ...(nonneg(o.startedAt) !== undefined ? { startedAt: nonneg(o.startedAt) } : {}),
+      ...(state === "error" && str(o.error, PROGRESS_ERROR_MAX) ? { error: str(o.error, PROGRESS_ERROR_MAX) } : {}),
+      ...(o.cached === true ? { cached: true as const } : {}),
+      ...(o.skipped === true ? { skipped: true as const } : {}),
+    });
+  }
+  // Empty = a plain Agent-task heartbeat, forwarded as liveness evidence
+  // (see the header) — the workflow delta folder ignores it (no entries),
+  // and only the background-work declare consumes it.
+  const workflow = [...phases, ...agents.slice(-PROGRESS_AGENTS_MAX)];
+  const toolUseId = typeof p.tool_use_id === "string" && p.tool_use_id.length > 0 ? p.tool_use_id : null;
+  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_progress",
+    taskId: clip(taskId, 128),
+    ...(toolUseId ? { toolUseId: clip(toolUseId, 128) } : {}),
+    ...(tokens !== undefined || toolUses !== undefined || durationMs !== undefined
+      ? { usage: {
+          ...(tokens !== undefined ? { tokens } : {}),
+          ...(toolUses !== undefined ? { toolUses } : {}),
+          ...(durationMs !== undefined ? { durationMs } : {}),
+        } }
+      : {}),
+    workflow,
+    timestamp,
+  };
+}
+
+// ── Context compaction (the harness summarizing its own conversation) ───────
+//
+// Captured live against 2.1.212 (the baked E2B pin) and 2.1.241 — identical
+// wire shapes on both, `/compact` and forced-auto alike:
+//
+//   {"type":"system","subtype":"status","status":"compacting"}
+//   {"type":"system","subtype":"status","status":null,
+//    "compact_result":"success"|"failed"[,"compact_error":"…"]}
+//   {"type":"system","subtype":"init",…}                (fresh init, success only)
+//   {"type":"system","subtype":"compact_boundary","compact_metadata":
+//     {"trigger":"auto"|"manual","pre_tokens":N,"post_tokens":N,
+//      "cumulative_dropped_tokens":N,"duration_ms":N,"preserved_segment":…}}
+//
+// Followed by the continuation summary as a SYNTHETIC user message (string
+// content, `isSynthetic: true`) — deliberately NOT forwarded: it quotes
+// conversation content verbatim (its "All user messages" section replays
+// platform notices word for word), which is exactly how the 2026-08-23
+// incident re-labeled a platform system notice as a "recalled memory".
+// The boundary does not replay on later resumes (verified live).
+//
+// A compaction spans 13-21s in the small captures and MINUTES at real
+// context sizes — forwarding the lifecycle is what lets downstream render
+// the silence as work instead of death (the 94%-auto-compact dead-air
+// incident).
+
+const COMPACT_ERROR_MAX = 500;
+
+/** One `system` event of the compaction family mapped onto the structured
+ *  lifecycle message, or null when the event is not compaction-shaped (a
+ *  plain `status` event with neither the compacting status nor a
+ *  compact_result stays unmapped). Pure and tolerant over untrusted harness
+ *  JSON. Exported for tests. */
+export function parseSystemCompaction(
+  p: Record<string, unknown>, timestamp: string,
+): AgentMessageCompaction | null {
+  const nonneg = (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+  if (p.subtype === "status") {
+    if (p.status === "compacting") return { type: "compaction", phase: "start", timestamp };
+    if (typeof p.compact_result === "string") {
+      const failed = p.compact_result !== "success";
+      const error = typeof p.compact_error === "string" && p.compact_error.length > 0
+        ? clip(p.compact_error, COMPACT_ERROR_MAX) : undefined;
+      return {
+        type: "compaction", phase: "settled",
+        result: failed ? "failed" : "success",
+        ...(failed && error ? { error } : {}),
+        timestamp,
+      };
+    }
+    return null;
+  }
+  if (p.subtype !== "compact_boundary") return null;
+  const meta = (typeof p.compact_metadata === "object" && p.compact_metadata !== null
+    ? p.compact_metadata : {}) as Record<string, unknown>;
+  const preTokens = nonneg(meta.pre_tokens);
+  const postTokens = nonneg(meta.post_tokens);
+  const droppedTokens = nonneg(meta.cumulative_dropped_tokens);
+  const durationMs = nonneg(meta.duration_ms);
+  return {
+    type: "compaction", phase: "boundary",
+    trigger: meta.trigger === "manual" ? "manual" : "auto",
+    ...(preTokens !== undefined ? { preTokens } : {}),
+    ...(postTokens !== undefined ? { postTokens } : {}),
+    ...(droppedTokens !== undefined ? { droppedTokens } : {}),
+    ...(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
@@ -247,6 +450,14 @@ export const claudeCodeSpec: CliAgentSpec = {
   streamInput: {
     promptLine: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: prompt } }),
     messageLine: (text) => JSON.stringify({ type: "user", message: { role: "user", content: text } }),
+    // The ESC equivalent (verified live against claude 2.1.236): the CLI's
+    // control layer processes this OUT OF BAND — a 120s foreground Bash call
+    // aborted 6s in, the control_response answered instantly, the run ended
+    // ~100ms later with `result: error_during_execution`, and `--resume` on
+    // the same session id kept the full turn context.
+    interruptLine: (requestId) => JSON.stringify({
+      type: "control_request", request_id: requestId, request: { subtype: "interrupt" },
+    }),
   },
   buildCommand: ({ promptPath, sessionId, model, cwd, effort, streamInput }) => {
     const flags = [
@@ -285,9 +496,10 @@ export const claudeCodeSpec: CliAgentSpec = {
     // tool_use id; null at top level). Forwarded on tool_use/tool_result so
     // renderers can nest child activity under the spawning call instead of
     // flattening it into the parent transcript unattributed.
-    const parent = typeof p.parent_tool_use_id === "string" && p.parent_tool_use_id.length > 0
-      ? { parentToolUseId: p.parent_tool_use_id }
-      : {};
+    const parentId = typeof p.parent_tool_use_id === "string" && p.parent_tool_use_id.length > 0
+      ? p.parent_tool_use_id
+      : undefined;
+    const parent = parentId ? { parentToolUseId: parentId } : {};
     switch (p.type) {
       // Assistant API message: content blocks → text / thinking / tool_use.
       case "assistant": {
@@ -321,12 +533,25 @@ export const claudeCodeSpec: CliAgentSpec = {
       // 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.
+      // never forwarded raw. TOP-LEVEL user text (the echo of the prompt,
+      // system reminders) stays unmapped: it is not agent output. SIDECHAIN
+      // user text (parent_tool_use_id present) is a message landing in a
+      // CHILD's thread — the delivered form of a SendMessage steer to a
+      // running subagent ("queued for delivery at its next tool round") —
+      // and forwards as `subagent_user_message` so the steer renders inside
+      // the child's mini-session instead of vanishing (task #97; before
+      // this, a queued steer was visible only as the parent's opaque
+      // SendMessage tool call).
       case "user": {
         const message = p.message as { content?: ClaudeContentBlock[] | string } | undefined;
+        // HARNESS-synthesized user messages (`isSynthetic` — e.g. a
+        // post-compaction continuation summary, including a CHILD's own)
+        // are never a delivered steer: suppress the steer arm, keep the
+        // notification parse. Structural marker only, same doctrine as the
+        // `<synthetic>` model stamp above.
+        const steerParent = p.isSynthetic === true ? undefined : parentId;
         if (typeof message?.content === "string") {
-          return parseTaskNotifications(message.content, ts);
+          return sidechainAwareUserText(message.content, steerParent, ts);
         }
         const blocks = Array.isArray(message?.content) ? message.content : [];
         return blocks.flatMap((b): AgentMessage[] => {
@@ -337,7 +562,7 @@ export const claudeCodeSpec: CliAgentSpec = {
             }];
           }
           if (b.type === "text" && typeof b.text === "string") {
-            return parseTaskNotifications(b.text, ts);
+            return sidechainAwareUserText(b.text, steerParent, ts);
           }
           return [];
         });
@@ -410,11 +635,23 @@ export const claudeCodeSpec: CliAgentSpec = {
       // 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.
+      // header above), and `task_progress` the LIVE background-task feed
+      // (parseSystemTaskProgress): per-agent workflow entries for Workflow
+      // tasks, `workflow: []` heartbeats for plain background Agent tasks —
+      // both forward so the platform can declare the running task as
+      // session background work. Compaction rides here as well (the status
+      // pair + compact_boundary — parseSystemCompaction). Everything else
+      // under system (task_started, task_updated, background_tasks_changed,
+      // thinking_tokens) is lifecycle noise here.
       case "system": {
+        if (p.subtype === "task_progress") {
+          const progress = parseSystemTaskProgress(p, ts);
+          return progress ? [progress] : [];
+        }
+        if (p.subtype === "status" || p.subtype === "compact_boundary") {
+          const compaction = parseSystemCompaction(p, ts);
+          return compaction ? [compaction] : [];
+        }
         if (p.subtype !== "task_notification") return [];
         const notification = parseSystemTaskNotification(p, ts);
         return notification ? [notification] : [];

package/src/runtimes/openai-desktop.ts

@@ -3,6 +3,17 @@
  *
  * Works against DesktopSandboxProvider — no E2B SDK dependency here.
  * The action→screenshot loop runs until the model emits text, then yields it.
+ *
+ * COORDINATE SPACES (incident note). Every screenshot is downscaled to the
+ * model's DISPLAY geometry (1024×720) before it is sent, so the model emits
+ * coordinates in the SCALED screenshot's space — never the real desktop's.
+ * An earlier revision executed those coordinates against the real desktop
+ * using hardcoded real-geometry constants, so on any sandbox whose actual
+ * geometry differed, every click landed in the wrong place. The provider has
+ * no geometry call, so the real geometry is read from each screenshot buffer
+ * itself (sharp metadata), and the resulting per-capture `CaptureScale` maps
+ * the model's coordinates back onto the exact frame it saw. The old constants
+ * survive ONLY as a fallback for the metadata-missing case.
  */
 
 import OpenAI from "openai";
@@ -12,8 +23,11 @@ import { defineRuntime, formatError } from "../index.js";
 
 const DISPLAY_WIDTH  = 1024;
 const DISPLAY_HEIGHT = 720;
-const DESKTOP_WIDTH  = 1280;
-const DESKTOP_HEIGHT = 800;
+/** FALLBACK real-desktop geometry — consulted ONLY when sharp cannot read a
+ *  screenshot's dimensions. The truth is derived per capture from the raw
+ *  screenshot buffer itself (see `captureScaledScreenshot`). */
+const FALLBACK_DESKTOP_WIDTH  = 1280;
+const FALLBACK_DESKTOP_HEIGHT = 800;
 const MAX_TURNS = 40;
 
 export interface OpenAIDesktopRunnerOptions extends RuntimeOptions {
@@ -27,8 +41,9 @@ export interface OpenAIDesktopRunnerOptions extends RuntimeOptions {
 // so the exchange is described here instead of with SDK types.
 
 /** One model-emitted desktop action. Coordinates arrive in DISPLAY (model)
- *  space and are rescaled to the real desktop before dispatch. */
-interface ComputerAction {
+ *  space and are rescaled through the CURRENT capture's `CaptureScale`
+ *  before dispatch. Exported so tests can type their fixtures. */
+export interface ComputerAction {
   type: string;
   coordinate?: [number, number];
   startCoordinate?: [number, number];
@@ -99,12 +114,16 @@ export class OpenAIDesktopRunner implements ModelExecutionContract {
 
     yield { type: "init", sessionId: "e2b-desktop", timestamp: ts() };
 
-    const screenshot = await captureScaledScreenshot(sandbox);
+    const first = await captureScaledScreenshot(sandbox);
+    // The scale of the LATEST frame the model has seen — its next batch of
+    // coordinates is in that frame's space, so every fresh capture below
+    // replaces this before the frame is sent back.
+    let scale = first.scale;
 
     const messages: InputMessage[] = [{
       role: "user",
       content: [
-        { type: "input_image", image_url: `data:image/png;base64,${screenshot}` },
+        { type: "input_image", image_url: `data:image/png;base64,${first.b64}` },
         { type: "input_text", text: opts.prompt },
       ],
     }];
@@ -137,7 +156,7 @@ export class OpenAIDesktopRunner implements ModelExecutionContract {
 
       for (const call of computerCalls) {
         console.log(`${label}   → ${call.action.type}`);
-        await executeAction(sandbox, call.action).catch(
+        await executeAction(sandbox, call.action, scale).catch(
           (err: unknown) => console.warn(`${label}   Action failed (non-fatal): ${formatError(err)}`),
         );
       }
@@ -145,10 +164,11 @@ export class OpenAIDesktopRunner implements ModelExecutionContract {
       if (computerCalls.length === 0) break;
 
       const next = await captureScaledScreenshot(sandbox);
+      scale = next.scale;
       messages.push({ role: "user", content: computerCalls.map((call): InputPart => ({
         type: "computer_call_output",
         call_id: call.call_id,
-        output: { type: "input_image", image_url: `data:image/png;base64,${next}` },
+        output: { type: "input_image", image_url: `data:image/png;base64,${next.b64}` },
       })) });
     }
 
@@ -160,21 +180,58 @@ export class OpenAIDesktopRunner implements ModelExecutionContract {
 // Helpers — work against DesktopSandboxProvider interface
 // ---------------------------------------------------------------------------
 
-async function captureScaledScreenshot(sandbox: DesktopSandboxProvider): Promise<string> {
+/** Real-desktop pixels per model-DISPLAY pixel, derived from ONE capture.
+ *  Coordinates the model emits against that capture are multiplied by these
+ *  factors (and rounded) before touching the provider. */
+export interface CaptureScale {
+  scaleX: number;
+  scaleY: number;
+}
+
+/** One captured frame: the model-facing image plus the scale that maps the
+ *  model's coordinates back onto this frame's real desktop. */
+export interface ScaledCapture {
+  /** Base64 PNG resized to DISPLAY_WIDTH×DISPLAY_HEIGHT (fit "fill"). */
+  b64: string;
+  scale: CaptureScale;
+}
+
+/** Derive a capture's scale from its real pixel dimensions. The constants
+ *  are a FALLBACK only — used when sharp cannot read the frame's metadata;
+ *  a real dimension always wins. */
+export function scaleFromDimensions(width: number | undefined, height: number | undefined): CaptureScale {
+  return {
+    scaleX: (width  ?? FALLBACK_DESKTOP_WIDTH)  / DISPLAY_WIDTH,
+    scaleY: (height ?? FALLBACK_DESKTOP_HEIGHT) / DISPLAY_HEIGHT,
+  };
+}
+
+/** Capture one frame: read the REAL geometry from the raw screenshot's own
+ *  metadata, downscale to the model's DISPLAY geometry, and return both the
+ *  image and the scale that maps model coordinates back onto this frame. */
+export async function captureScaledScreenshot(sandbox: DesktopSandboxProvider): Promise<ScaledCapture> {
   const raw = await sandbox.screenshot();
-  const scaled = await sharp(raw)
+  const image = sharp(raw);
+  const { width, height } = await image.metadata();
+  const scaled = await image
     .resize(DISPLAY_WIDTH, DISPLAY_HEIGHT, { kernel: "lanczos3", fit: "fill" })
     .png()
     .toBuffer();
-  return scaled.toString("base64");
+  return { b64: scaled.toString("base64"), scale: scaleFromDimensions(width, height) };
 }
 
-function scaleX(x: number): number { return Math.round(x * DESKTOP_WIDTH / DISPLAY_WIDTH); }
-function scaleY(y: number): number { return Math.round(y * DESKTOP_HEIGHT / DISPLAY_HEIGHT); }
-
-async function executeAction(sandbox: DesktopSandboxProvider, action: ComputerAction): Promise<void> {
+/** Dispatch one model action against the provider, mapping every coordinate
+ *  through the CURRENT capture's scale. Non-coordinate payloads — scroll
+ *  deltas (ticks), typed text, key chords — pass through untouched. */
+export async function executeAction(
+  sandbox: DesktopSandboxProvider,
+  action: ComputerAction,
+  scale: CaptureScale,
+): Promise<void> {
+  const mapX = (x: number) => Math.round(x * scale.scaleX);
+  const mapY = (y: number) => Math.round(y * scale.scaleY);
   const [x, y] = action.coordinate
-    ? [scaleX(action.coordinate[0]), scaleY(action.coordinate[1])]
+    ? [mapX(action.coordinate[0]), mapY(action.coordinate[1])]
     : [0, 0];
 
   switch (action.type) {
@@ -185,12 +242,18 @@ async function executeAction(sandbox: DesktopSandboxProvider, action: ComputerAc
     case "move":         await sandbox.moveMouse(x, y); break;
     case "type":         await sandbox.write(action.text ?? ""); break;
     case "key":          await sandbox.press(action.key ?? ""); break;
-    case "scroll":       await sandbox.scroll(action.direction === "up" ? "up" : "down", action.ticks ?? 3); break;
+    case "scroll":
+      // The scroll POSITION is a coordinate — mapped (the provider has no
+      // positional scroll, so position lands via moveMouse). The scroll
+      // DELTA (ticks) is not a coordinate — untouched.
+      if (action.coordinate) await sandbox.moveMouse(x, y);
+      await sandbox.scroll(action.direction === "up" ? "up" : "down", action.ticks ?? 3);
+      break;
     case "drag":
       if (action.startCoordinate && action.endCoordinate) {
         await sandbox.drag(
-          [scaleX(action.startCoordinate[0]), scaleY(action.startCoordinate[1])],
-          [scaleX(action.endCoordinate[0]), scaleY(action.endCoordinate[1])],
+          [mapX(action.startCoordinate[0]), mapY(action.startCoordinate[1])],
+          [mapX(action.endCoordinate[0]), mapY(action.endCoordinate[1])],
         );
       }
       break;

package/src/sandbox/devbox.ts

@@ -5,13 +5,13 @@
  * This module is the SINGLE SOURCE for the machine's template identity: the
  * recipe lives in `infra/e2b-template/devbox.ts`, `infra/e2b-template/build.ts`
  * bakes it under the alias below, and the server imports the alias from here to
- * provision a machine (exactly how `e2bBaseTemplate` reaches the E2B provider —
- * a stable ALIAS, never a snapshot id, so the same string resolves in whichever
- * E2B account a deployment uses).
+ * provision a machine (exactly how `e2bAgentEnvTemplate` reaches the E2B
+ * provider — a stable ALIAS, never a snapshot id, so the same string resolves
+ * in whichever E2B account a deployment uses).
  *
  * Interactive only. Workflow RUNS never execute on a devbox (ADR-0038 §2.6):
- * runs boot the clean per-size `agent-compose-base-<size>` / `agent-env-<size>`
- * templates so reproducibility never inherits hand-configured drift.
+ * runs boot the clean per-size `agent-env-<size>` template (the same image
+ * sessions boot) so reproducibility never inherits hand-configured drift.
  */
 
 /** Stable E2B template ALIAS for the per-member desktop machine. Baked by

package/src/sandbox/providers/e2b.ts

@@ -5,7 +5,7 @@
  * registry entry.
  */
 
-import { Sandbox } from "e2b";
+import { Sandbox, Template } from "e2b";
 import type { CommandHandle } from "e2b";
 import type { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
@@ -13,7 +13,7 @@ import type {
   SandboxProvider, SandboxCommandRunOptions, SandboxBackgroundProcess, SandboxPtyHandle,
 } from "../../types/sandbox.js";
 import { toE2bNetwork } from "../network-policy.js";
-import { DEFAULT_SANDBOX_SIZE, e2bBaseTemplate, isE2bSupportedSize } from "../sizes.js";
+import { DEFAULT_SANDBOX_SIZE, e2bAgentEnvTemplate, isE2bSupportedSize } from "../sizes.js";
 import { AGENT_COMPOSE_TAG } from "../provider-def.js";
 import type { OwnedSandbox, SandboxProviderDef } from "../provider-def.js";
 
@@ -297,18 +297,24 @@ export const e2bProviderDef: SandboxProviderDef = {
   // E2B has no create-time resource knob (specs are baked into the
   // template/snapshot), so honouring `size` on E2B = picking a PRE-SIZED
   // template, not passing the field through. We resolve the boot template
-  // from `size` below (`e2bBaseTemplate(size)`) when the caller gave no
+  // from `size` below (`e2bAgentEnvTemplate(size)`) when the caller gave no
   // explicit template/bootFrom; the field itself is never forwarded to E2B.
   create: async ({ template, timeoutMs, networkPolicy, size, ...rest }) => {
     // `template` is an E2B template id/alias, a snapshot id (a valid create
     // source that persists beyond its origin sandbox — bootFrom parity), or
-    // absent. When absent we pick the SIZE-MATCHED platform base alias
-    // (`agent-compose-base-<size>`) so `resources.size` gives the same
-    // machine spec on E2B as on Vercel — the cross-provider parity this whole
-    // change exists for. Only when no size is resolvable at all do we fall
-    // back to E2B_DEFAULT_TEMPLATE if set (a prebuilt base — e.g. one with the claude CLI
-    // + chromium baked in and more RAM than the stock 482MB base), the
-    // per-deployment analogue of Vercel's node24; else E2B's stock base.
+    // absent. When absent we pick the SIZE-MATCHED platform agent-env alias
+    // (`agent-env-<size>`) — the SAME image every cloud session boots
+    // (server/src/sandbox/persistent.ts resolves the identical
+    // `e2bAgentEnvTemplate(size)`), so a template-less workflow run gets the
+    // full session toolchain (claude runtime, dev toolbelt, agentc, fsgw
+    // client) instead of a thinner image. One seam, both lanes: the
+    // session/run divergence that caused fleet-wide `exit 127`s (missing
+    // harness CLIs, fixed by on-demand install in v0.10.73) is structurally
+    // gone — there is no separate run-lane template to drift. The per-size
+    // aliasing also keeps `resources.size` giving the same machine spec on
+    // E2B as on Vercel (cross-provider parity). Only when no size is
+    // resolvable at all do we fall back to E2B_DEFAULT_TEMPLATE if set (the
+    // per-deployment analogue of Vercel's node24); else E2B's stock base.
     // Self-provisioning runtimes (claude/codex/amp via bootFrom:"reuse") install
     // their CLI on the base and cache it in the captured snapshot, so a
     // template-less first run boots, installs, snapshots. Clamp the lifetime to
@@ -346,18 +352,19 @@ export const e2bProviderDef: SandboxProviderDef = {
     };
     // Boot template resolution, in priority order:
     //   1. explicit `template`/bootFrom (a pinned snapshot or alias),
-    //   2. else the SIZE-MATCHED base alias `agent-compose-base-<size>`
-    //      (`size` resolved to DEFAULT_SANDBOX_SIZE when unset) — this is the
-    //      cross-provider parity path,
+    //   2. else the SIZE-MATCHED agent-env alias `agent-env-<size>` — the
+    //      session-identical image (`size` resolved to DEFAULT_SANDBOX_SIZE
+    //      when unset). NEVER the legacy `agent-compose-base-<size>` — that
+    //      family remains a valid EXPLICIT bootFrom target only,
     //   3. else E2B_DEFAULT_TEMPLATE as an ultimate per-deployment fallback,
     //   4. else E2B's stock base.
-    // `32vcpu-64gb` has no base-<size> template (Pro caps ~8 vCPU); the
+    // `32vcpu-64gb` has no per-size template (Pro caps ~8 vCPU); the
     // register + invoke guards reject it before a run reaches here, so we
-    // never synthesize a non-existent `agent-compose-base-32vcpu-64gb` alias.
+    // never synthesize a non-existent `agent-env-32vcpu-64gb` alias.
     const resolvedSize = size ?? DEFAULT_SANDBOX_SIZE;
     const tmpl =
       template ??
-      (isE2bSupportedSize(resolvedSize) ? e2bBaseTemplate(resolvedSize) : undefined) ??
+      (isE2bSupportedSize(resolvedSize) ? e2bAgentEnvTemplate(resolvedSize) : undefined) ??
       process.env.E2B_DEFAULT_TEMPLATE;
     return makeE2bSandboxProvider(
       await (tmpl ? Sandbox.create(tmpl, sandboxOpts) : Sandbox.create(sandboxOpts)),
@@ -383,4 +390,41 @@ export const e2bProviderDef: SandboxProviderDef = {
     // E2B snapshots are team-scoped; delete by id. Best-effort like Vercel's.
     await Sandbox.deleteSnapshot(snapshotId, { apiKey: env.E2B_API_KEY });
   },
+  snapshotExists: async (snapshotId, env) => {
+    // Existence probe for a CREATE SOURCE (the `snapshotResolves` contract:
+    // `true` = resolves, `false` = the provider definitively says it does not
+    // exist, anything indeterminate PROPAGATES — never reported as missing).
+    //
+    // e2b 2.30.5 has no GET-snapshot-by-id, so this composes the two
+    // documented lookups, cheapest first:
+    //   1. `Template.exists` — ONE round-trip to the template-existence
+    //      endpoint (`GET /templates/aliases/{alias}`), with DOCUMENTED
+    //      not-found semantics: 404 → false, 403 → exists but owned by
+    //      another team → true (the SDK's own mapping). Snapshots are
+    //      templates provider-side, and this probe also resolves the
+    //      `agent-env-*` template ALIASES that E2B-pinned default templates
+    //      register as their bootFrom — boot-time platform validation
+    //      (validatePlatformSnapshots) probes those through this same seam,
+    //      so a snapshots-only lookup would falsely alert "unresolvable" on
+    //      every alias.
+    //   2. A paged scan of the team's snapshot list (`Sandbox.listSnapshots`)
+    //      — authoritative for `createSnapshot` artifacts whatever their id
+    //      shape, reached only when the template probe answered not-found.
+    //      Bounded by the team's snapshot count (session rings are GC'd to a
+    //      fixed retain depth), and this is rare-path code: machine-loss
+    //      recovery and boot validation, never a hot loop.
+    // `false` therefore means BOTH documented lookups answered not-found.
+    // (`Sandbox.listSnapshots({ sandboxId })` — source-filtered — was
+    // rejected as the primary: callers hold only the snapshot id, and a
+    // filtered miss would still need the full scan before "absent" is
+    // honest.) Transport/auth faults from either call throw — indeterminate.
+    const opts = { apiKey: env.E2B_API_KEY };
+    if (await Template.exists(snapshotId, opts)) return true;
+    const paginator = Sandbox.listSnapshots(opts);
+    while (paginator.hasNext) {
+      const items = await pRetry(() => paginator.nextItems(), { retries: 3, minTimeout: 500, factor: 2 });
+      if (items.some((s) => s.snapshotId === snapshotId || s.names.includes(snapshotId))) return true;
+    }
+    return false;
+  },
 };