@agent-compose/sdk 0.8.3 → 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,17 +496,27 @@ 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": {
-        const message = p.message as { content?: ClaudeContentBlock[] } | undefined;
+        const message = p.message as { content?: ClaudeContentBlock[]; model?: unknown } | undefined;
+        // HARNESS-synthesized assistant messages: the CLI stamps
+        // `message.model: "<synthetic>"` on content it composed itself —
+        // slash-command stdout, model/skills advisories — never the model
+        // speaking (verified live on claude 2.1.212 and 2.1.236: /model and
+        // /context output both arrive this way). Their text forwards as
+        // `harness_notice` so downstream renders it as a quiet system note
+        // instead of agent prose (the 2026-08-22 plumbing-as-content leak).
+        // Structural marker only — no content sniffing.
+        const synthetic = message?.model === "<synthetic>";
         const blocks = Array.isArray(message?.content) ? message.content : [];
         return blocks.flatMap((b): AgentMessage[] => {
           if (b.type === "text" && typeof b.text === "string" && b.text.length > 0) {
-            return [{ type: "text", text: b.text, timestamp: ts }];
+            return [{ type: synthetic ? "harness_notice" : "text", text: b.text, timestamp: ts }];
           }
           if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.length > 0) {
             return [{ type: "thinking", text: b.thinking, timestamp: ts }];
@@ -312,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[] => {
@@ -328,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 [];
         });
@@ -401,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