@agent-compose/sdk 0.5.5 → 0.5.7

package/dist/runtimes/_cli-agent.d.ts

@@ -12,14 +12,16 @@
  * AsyncQueue bridge → init/usage/done/error lifecycle), parameterised per-CLI
  * by a `CliAgentSpec`.
  *
- * Requirements (per spec): the provider CLI is installed in the sandbox image,
- * and the provider's API key is present in the sandbox environment (see each
- * spec's `authEnv`). `commands.run` inherits the sandbox env, so secrets set via
- * `agentc secrets set` are visible to the CLI.
- *
- * NOTE: the per-CLI command construction + resume flags + exact event shapes in
- * the shipped specs are mapped from each tool's docs and have NOT been verified
- * against a live CLI run — verify before relying on them in production.
+ * Provisioning (per spec): the runtime installs the provider CLI on demand —
+ * `command -v <bin>` before the first turn, falling back to the spec's
+ * `install` command when it's absent — so it works on a bare sandbox with no
+ * manual setup or hardcoded snapshot id. Pair it with
+ * `snapshots: { bootFrom: "reuse" }` on the workflow and the install happens
+ * exactly once: the first run installs the CLI and captures a snapshot, and
+ * every run after boots from that snapshot with the CLI already present (the
+ * probe short-circuits). The provider's API key must be in the sandbox env
+ * (see each spec's `authEnv`); `commands.run` inherits the sandbox env, so
+ * values set via `agentc secrets set` are visible to the CLI.
  */
 import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider } from "../index.js";
 /** Single-quote a value for safe interpolation into a `sh -c` command line. */
@@ -34,6 +36,15 @@ export interface CliAgentSpec {
     authEnv: string;
     /** Default model id when none is configured; omit to let the CLI choose. */
     defaultModel?: string;
+    /** Binary the runtime spawns (`codex`, `amp`). Probed with `command -v`
+     *  before the first turn; if absent, `install` provisions it. */
+    bin: string;
+    /** Shell command that installs `bin` when it's missing from the sandbox.
+     *  Runs at most once per runner, and only when the probe fails — so booting
+     *  from a snapshot that already has the CLI (the steady state under
+     *  `snapshots: { bootFrom: "reuse" }`) skips it. Must leave `bin` resolvable
+     *  on a non-login shell's PATH (the runtime spawns via `sh -c`). */
+    install: string;
     /** Serialise the user prompt into the bytes written to the prompt file —
      *  plain text for a CLI that reads the prompt from stdin (codex `-`), or a
      *  JSONL user message for a `--stream-json-input` CLI (amp). */
@@ -62,6 +73,12 @@ export declare class CliAgentRunner implements ModelExecutionContract {
     readonly kind: string;
     constructor(sandbox: SandboxProvider, options: RuntimeOptions, spec: CliAgentSpec, configModel?: string | undefined);
     get model(): string | undefined;
+    private installed;
+    /** Provision the CLI on demand. A no-op once `bin` is on PATH — the steady
+     *  state under `snapshots: { bootFrom: "reuse" }`, where the first run's
+     *  install is baked into the snapshot every later run boots from. So the
+     *  install command runs exactly once: on the first run of a content hash. */
+    private ensureInstalled;
     sendMessage(opts: {
         prompt: string;
         sessionId?: string;

package/dist/runtimes/amp.d.ts

@@ -5,13 +5,14 @@
  * own loop + tools, so we only stream-parse what it prints.
  *
  * Auth: set `AMP_API_KEY` (`sgamp_…`) in the sandbox env via a workflow secret.
- * Requires the `amp` CLI (`@ampcode/cli`) installed in the sandbox image. The
- * model is chosen by the AMP_API_KEY account (e.g. a GPT-only token runs GPT);
- * the runtime doesn't pin a model.
+ * The runtime installs the `amp` CLI (`@ampcode/cli`) on demand — no image
+ * baking needed; pair with `snapshots: { bootFrom: "reuse" }` to install once
+ * and boot from the captured snapshot on every run after. The model is chosen
+ * by the AMP_API_KEY account (e.g. a GPT-only token runs GPT); the runtime
+ * doesn't pin a model.
  *
- * ⚠️ NOT verified against a live `amp` run — the thread-continue syntax and the
- * exact assistant/result shapes are mapped from the docs (ampcode.com). Verify
- * before production use.
+ * Verified against a live `amp -x --stream-json` run: the user-message stdin
+ * shape, assistant content blocks, and result usage below all round-trip.
  */
 export interface AmpRuntimeConfig {
     /** Amp uses its configured model; reserved for forward-compatibility. */

package/dist/runtimes/claude.d.ts

@@ -7,7 +7,11 @@ export interface ClaudeRuntimeConfig {
     claudeMdContent?: string;
     /** Env overrides for Agent SDK provider routing. */
     env?: Record<string, string>;
-    /** Model to use. Defaults to DEFAULT_CLAUDE_MODEL. */
+    /** Model to use. Accepts a caliber shorthand — "fable" (most capable),
+     *  "opus", "sonnet", "haiku" (fastest/cheapest) — or an exact model id.
+     *  Defaults to DEFAULT_CLAUDE_MODEL (Fable). Orchestrators pick a caliber
+     *  per agent: fable/opus for planning + implementation, sonnet for focused
+     *  single-responsibility work, haiku for mechanical tasks. */
     model?: string;
     /** MCP servers to configure for the Agent SDK. */
     mcpServers?: Record<string, {
@@ -21,6 +25,10 @@ export interface ClaudeRuntimeConfig {
     thinking?: ThinkingConfig;
     /** Reasoning effort hint for models that support adaptive thinking. */
     effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    /** Skills to enable for the agent (the Agent SDK's `skills` option — also
+     *  auto-adds the `Skill` tool). The agent-env bakes the `/ac:*` skills via
+     *  `agentc init`; default `"all"` makes them usable. Pass `[]` to disable. */
+    skills?: string[] | "all";
 }
 export declare class ClaudeRunner implements ModelExecutionContract {
     private readonly options;

package/dist/runtimes/cli-agent.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CliAgentRunner self-provisioning — the runtime installs its CLI on demand
+ * (`command -v <bin>` → install if missing), runs the install at most once per
+ * runner, and surfaces an install failure as an `error` message rather than
+ * blowing up. This is what lets `createCodexRuntime()` work on a bare sandbox
+ * with no image baking, and lets `snapshots: { bootFrom: "reuse" }` collapse
+ * the install to a one-time cost.
+ */
+export {};

package/dist/runtimes/codex.d.ts

@@ -4,12 +4,13 @@
  * Built on the shared CLI-agent base; Codex brings its own loop + tools, so we
  * only stream-parse what it prints.
  *
- * Auth: set `CODEX_API_KEY` (or `OPENAI_API_KEY`) in the sandbox env via a
- * workflow secret. Requires the `codex` CLI installed in the sandbox image.
+ * 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.
  *
- * ⚠️ NOT verified against a live `codex` run — the resume flag and the exact
- * item shapes (command_execution / reasoning fields) are mapped from the docs
- * (developers.openai.com/codex/noninteractive). Verify before production use.
+ * Verified against codex-cli 0.124.0: `codex exec --json` + resume-by-thread,
+ * with the command_execution / reasoning / agent_message item shapes below.
  */
 export interface CodexRuntimeConfig {
     /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */