@agent-compose/sdk 0.8.4 → 0.8.6

package/dist/runtimes/codex.d.ts

@@ -5,14 +5,102 @@
  * only stream-parse what it prints.
  *
  * Auth: set `OPENAI_API_KEY` (or `CODEX_API_KEY`) in the sandbox env via a
- * workflow secret. The runtime installs the `codex` CLI (`@openai/codex`) on
- * demand — no image baking needed; pair with `snapshots: { bootFrom: "reuse" }`
- * to install once and boot from the captured snapshot on every run after.
+ * workflow secret. The E2B session image bakes the pinned `codex` CLI
+ * (`@openai/codex@CODEX_CLI_VERSION`); on any other machine the runtime
+ * installs that same version on demand (pair with
+ * `snapshots: { bootFrom: "reuse" }` to install once and boot from the
+ * captured snapshot on every run after).
  *
  * Verified against codex-cli 0.124.0: `codex exec --json` + resume-by-thread,
- * with the command_execution / reasoning / agent_message item shapes below.
+ * with the command_execution / reasoning / agent_message item shapes below;
+ * the plan's `todo_list` item against codex-rs rust-v0.153.4 and
+ * rust-v0.159.2 (see codexPlanMessages); the command_execution /
+ * agent_message / turn.completed shapes re-verified live against 0.160.0
+ * (the pin), whose plan-tool sources are byte-identical to rust-v0.159.2.
  */
 import { type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
+/** The Bash PreToolUse hook rtk installs for Codex (`rtk init -g --codex`
+ *  writes exactly this entry — matcher `Bash`, command `rtk hook codex` —
+ *  into $CODEX_HOME/hooks.json). `rtk hook codex` exists since rtk 0.50.0;
+ *  the image bakes RTK_VERSION (sandbox/baked-clis.ts), which this payload
+ *  was run against. Codex's shell tool matches the `Bash` matcher (codex-rs
+ *  rust-v0.160.0, the pinned CODEX_CLI_VERSION; identical at
+ *  rust-v0.159.2), and the hook runs under `$SHELL -lc` with the PreToolUse
+ *  JSON on stdin. `rtk hook codex` answers `permissionDecision: "allow"` +
+ *  `updatedInput` rewriting `git status` to `rtk git status` when it has a
+ *  filter for the command; Codex applies the replacement before its own
+ *  approval and sandbox checks. For a command it cannot compress (an
+ *  unknown tool, a pipe into one, substitutions, heredocs, redirects, a
+ *  `RTK_DISABLED=1` prefix, an unknown permission mode) it prints nothing
+ *  and exits 0, and Codex runs the original unchanged.
+ *
+ *  The wrapper fails OPEN both ways, like RTK_BASH_HOOK_COMMAND
+ *  (claude-code.ts). `command -v` covers an image without rtk (the devbox,
+ *  a bare Vercel VM): silent, exit 0, so Codex runs the command instead of
+ *  failing every shell call's hook with 127. The trailing `exit 0` covers
+ *  an rtk that cannot answer: Codex treats a PreToolUse hook's exit 2 with
+ *  stderr as a BLOCK of the tool call (codex-rs hooks/src/events/
+ *  pre_tool_use.rs at rust-v0.160.0 — the model reads "Command blocked by
+ *  PreToolUse hook: <stderr>"), and clap exits 2 with its usage on stderr
+ *  for a subcommand it does not know. That was 2026-10-03: the image's rtk
+ *  was a cache-served 0.45.0 with no `hook codex`, and this hook — `exec`
+ *  handing rtk's exit code to Codex — blocked every shell command of every
+ *  codex session. rtk's hooks never exit non-zero on purpose (they fail
+ *  open with no stdout), so a non-zero exit is always a broken rtk, and the
+ *  compressor must never cost the worker its shell: the exit code is
+ *  dropped, and the smoke gate's codex-rtk-hook-rewrite check is what
+ *  proves the rewrite itself. */
+export declare const RTK_CODEX_HOOK_COMMAND = "command -v rtk >/dev/null 2>&1 && rtk hook codex; exit 0";
+/** The PostToolUse command hook that carries a mid-turn message into a
+ *  RUNNING codex turn (the 2026-10-02 relayed-steer incident: three of the
+ *  owner's instructions waited 48-51 minutes for a codex build to end).
+ *  Codex runs it, under `$SHELL -lc` with the event JSON on stdin and the
+ *  codex process's own environment, after every tool call it completes
+ *  (codex-rs core/src/tools/registry.rs → hook_runtime.rs at rust-v0.160.0,
+ *  the pin). The launch wrapper exported the turn's inbox and delivered-
+ *  counter paths into that environment (sdk _cli-agent.ts
+ *  toolHookInboxFragment); the hook forwards the inbox lines past the
+ *  counter as the hook's `additionalContext`, which codex records as
+ *  developer context in the live turn's history before the model's next
+ *  request (hook_runtime.rs record_additional_contexts), then advances the
+ *  counter — the same ack the server's inject lane trusts for the stdin
+ *  lane. Not a platform turn (no inbox in the environment): silent, exit 0.
+ *  Codex's default spill threshold for a hook's additional context is 2,500
+ *  tokens (hooks/src/output_spill.rs); a longer message reaches the model
+ *  as a preview plus a file pointer, which a steer never is. */
+export declare const CODEX_MID_TURN_HOOK_COMMAND: string;
+/** $CODEX_HOME/hooks.json for every platform Codex session (the server
+ *  writes it at boot, session-runtime-config.ts). Codex only RUNS a
+ *  user-level hook it has persisted trust for — the TUI's review prompt
+ *  has no headless counterpart, and `--dangerously-bypass-hook-trust` would
+ *  run a cloned repository's `.codex/hooks.json` unreviewed too — so the
+ *  server also writes the trust record for each of these exact hooks into
+ *  the config.toml it generates (sandbox/codex-hooks.ts). Verified live
+ *  against codex 0.159.2 and 0.160.0 for the rtk hook: with the record,
+ *  `codex exec` rewrote `git status` through rtk with no bypass flag;
+ *  without it, the hook was skipped.
+ *
+ *  The PostToolUse group carries NO matcher: codex runs a matcher-less hook
+ *  after every tool it completes (hooks/src/events/common.rs
+ *  matches_matcher: an absent matcher is a match), so a mid-turn message
+ *  lands at the next tool step whatever the tool was. */
+export declare const CODEX_PLATFORM_HOOKS: {
+    readonly hooks: {
+        readonly PreToolUse: readonly [{
+            readonly matcher: "Bash";
+            readonly hooks: readonly [{
+                readonly type: "command";
+                readonly command: "command -v rtk >/dev/null 2>&1 && rtk hook codex; exit 0";
+            }];
+        }];
+        readonly PostToolUse: readonly [{
+            readonly hooks: readonly [{
+                readonly type: "command";
+                readonly command: string;
+            }];
+        }];
+    };
+};
 /** True when an error-item message is a known codex advisory (log-level
  *  noise), not a real error. Exported for tests. */
 export declare function isCodexAdvisoryNoise(text: string): boolean;
@@ -28,8 +116,8 @@ export declare function codexWriterLockPreflight(threadId: string, waitAttempts?
  *  `mapEvent` is the golden the ACP normaliser is asserted equal to. Not part
  *  of the public runtime surface — `createCodexRuntime` stays the entry point. */
 export declare const codexSpec: CliAgentSpec;
-/** The effort levels codex actually has (`model_reasoning_effort`):
- *  low|medium|high|xhigh — no "max" (that level is Claude Code's alone). */
+/** The effort levels this runtime passes to codex (`model_reasoning_effort`):
+ *  low|medium|high|xhigh, the levels every codex model takes. */
 export type CodexReasoningEffort = Exclude<CliReasoningEffort, "max">;
 export interface CodexRuntimeConfig {
     /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */

package/dist/runtimes/codex.mid-turn-hook.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * codex's mid-turn hook, run for real: the PostToolUse command hook
+ * (CODEX_MID_TURN_HOOK_COMMAND) executed under `sh` the way codex runs a
+ * command hook — the event JSON on stdin, the codex process's environment —
+ * against a constructed inbox, and the launch fragment that gives the codex
+ * process that environment (toolHookInboxFragment). These pin what the
+ * guest DOES: the JSON codex parses, the delivered counter the server's ack
+ * trusts, and silence everywhere else.
+ */
+export {};

package/dist/runtimes/openai-desktop.d.ts

@@ -3,11 +3,35 @@
  *
  * 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 type { DesktopSandboxProvider, AgentMessage, ModelExecutionContract, RuntimeOptions } from "../index.js";
 export interface OpenAIDesktopRunnerOptions extends RuntimeOptions {
     openaiKey: string;
 }
+/** One model-emitted desktop action. Coordinates arrive in DISPLAY (model)
+ *  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];
+    endCoordinate?: [number, number];
+    text?: string;
+    key?: string;
+    direction?: string;
+    ticks?: number;
+}
 export declare class OpenAIDesktopRunner implements ModelExecutionContract {
     private sandbox;
     readonly kind = "openai-desktop";
@@ -20,5 +44,31 @@ export declare class OpenAIDesktopRunner implements ModelExecutionContract {
         sessionId?: string;
     }): AsyncGenerator<AgentMessage>;
 }
+/** 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 declare function scaleFromDimensions(width: number | undefined, height: number | undefined): CaptureScale;
+/** 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 declare function captureScaledScreenshot(sandbox: DesktopSandboxProvider): Promise<ScaledCapture>;
+/** 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 declare function executeAction(sandbox: DesktopSandboxProvider, action: ComputerAction, scale: CaptureScale): Promise<void>;
 declare const _default: import("../index.js").AgentRuntime<DesktopSandboxProvider>;
 export default _default;