@aexhq/sdk 0.39.0 → 0.40.0

package/dist/_contracts/sdk-errors.js

@@ -38,17 +38,94 @@ export class CleanupError extends AexError {
 }
 /**
  * Thrown by SDK and CLI operations when the dashboard BFF returns a non-2xx
- * response. Carries the HTTP status and parsed body for the caller to inspect.
+ * response. Carries the HTTP status, the redacted parsed body, the server's
+ * STABLE {@link AexApiErrorCode} (when present), and a `requestId` for support.
+ * Construct via {@link import("./error-factory.js").apiErrorFromResponse} — the
+ * single wire→exception mapping — which dispatches to a typed subclass
+ * ({@link AexAuthError} / {@link AexIdempotencyConflictError} /
+ * {@link AexNotFoundError} / {@link AexRateLimitError}).
  */
 export class AexApiError extends AexError {
     status;
     body;
-    constructor(status, message, body) {
-        super("API_ERROR", message, body);
+    /** The server's stable error code, when the body carried a known one. */
+    apiCode;
+    /** Request id (body `requestId` or a response header) for support correlation. */
+    requestId;
+    constructor(status, message, body, options) {
+        super("API_ERROR", message, body, options?.cause === undefined ? undefined : { cause: options.cause });
         this.status = status;
         this.body = redactSecrets(body);
+        this.apiCode = options?.apiCode;
+        this.requestId = options?.requestId;
     }
 }
+/** 401/403 auth failure (token invalid/revoked/expired, forbidden, insufficient scope). */
+export class AexAuthError extends AexApiError {
+    /** The scope the endpoint required, when the server named it (insufficient_scope). */
+    requiredScope;
+    constructor(init) {
+        super(init.status, init.message, init.body, {
+            apiCode: init.apiCode,
+            requestId: init.requestId,
+            cause: init.cause
+        });
+        this.requiredScope = init.requiredScope;
+    }
+}
+/** 409 — the idempotency key was reused with a different request body. */
+export class AexIdempotencyConflictError extends AexApiError {
+    constructor(init) {
+        super(init.status, init.message, init.body, {
+            apiCode: init.apiCode,
+            requestId: init.requestId,
+            cause: init.cause
+        });
+    }
+}
+/** 404 — the requested resource was not found. */
+export class AexNotFoundError extends AexApiError {
+    constructor(init) {
+        super(init.status, init.message, init.body, {
+            apiCode: init.apiCode,
+            requestId: init.requestId,
+            cause: init.cause
+        });
+    }
+}
+/** 429 — the workspace hit a rate/concurrency limit; retry after a backoff. */
+export class AexRateLimitError extends AexApiError {
+    /** Suggested backoff (ms), when the server advertised one (Retry-After). */
+    retryAfterMs;
+    constructor(init) {
+        super(init.status, init.message, init.body, {
+            apiCode: init.apiCode,
+            requestId: init.requestId,
+            cause: init.cause
+        });
+        this.retryAfterMs = init.retryAfterMs;
+    }
+}
+/** True for a 401/403 authentication/authorization failure. */
+export function isAuthError(err) {
+    return err instanceof AexAuthError;
+}
+/** True for a 403 whose cause is a missing scope (`insufficient_scope`). */
+export function isInsufficientScope(err) {
+    return err instanceof AexAuthError && err.apiCode === "insufficient_scope";
+}
+/** True for a 409 idempotency-key reuse conflict. */
+export function isIdempotencyConflict(err) {
+    return err instanceof AexIdempotencyConflictError;
+}
+/** True for a 404 not-found error. */
+export function isNotFound(err) {
+    return err instanceof AexNotFoundError;
+}
+/** True for a 429 rate/concurrency-limit error. */
+export function isRateLimited(err) {
+    return err instanceof AexRateLimitError;
+}
 /**
  * Thrown when a BFF-bound request fails BEFORE any HTTP response exists — DNS
  * failure, connection refused, TLS error, socket reset. Wraps the raw fetch
@@ -67,6 +144,8 @@ export class AexNetworkError extends AexError {
     causeCode;
     /** Attempts made when a retry layer exhausted its budget; `1` otherwise. */
     attempts;
+    /** Total elapsed time (ms) across all attempts, when the retry layer set it. */
+    elapsedMs;
     constructor(args) {
         const causeCode = extractErrorCode(args.cause);
         super("NETWORK_ERROR", networkErrorMessage(args, causeCode), { method: args.method, host: args.host, path: args.path, ...(causeCode ? { code: causeCode } : {}) }, { cause: args.cause });
@@ -75,6 +154,7 @@ export class AexNetworkError extends AexError {
         this.path = args.path;
         this.causeCode = causeCode;
         this.attempts = args.attempts ?? 1;
+        this.elapsedMs = args.elapsedMs;
     }
 }
 function networkErrorMessage(args, causeCode) {

package/dist/_contracts/sdk-secrets.js

@@ -194,17 +194,42 @@ export function createRedactingStream(known = []) {
 function isSecretKey(key) {
     return /(?:api[_-]?key|authorization|token|secret|password|credential)/i.test(key);
 }
-/** A candidate run is a high-entropy secret if it is both information-dense
- * AND mixes character classes (the property that separates opaque secret blobs
- * from single-class identifiers/paths). */
+/**
+ * A candidate run is a high-entropy secret if it contains an opaque
+ * secret-shaped SEGMENT. The candidate class already excludes `_` so
+ * snake_case names split into sub-candidates; we ADDITIONALLY treat `-` as a
+ * segment boundary here, at the entropy layer, so a kebab-case human name or a
+ * timestamped slug is judged by its PARTS — dictionary words + a decimal number,
+ * each individually low-entropy — not by its (misleadingly high) whole-run
+ * entropy. Concretely a customer secret NAME like `spike17-race-1720000000000`
+ * (and its real-`Date.now()` variants, whose whole-run entropy is ~4.1) has no
+ * opaque segment and SURVIVES — a name is not a credential, and masking it makes
+ * `secret_not_found` unactionable.
+ *
+ * Splitting at the entropy layer (not in the candidate regex) is the precise,
+ * non-weakening choice: an OPAQUE base64url secret that merely CONTAINS a `-`
+ * still masks, because at least one of its `-`-segments is itself a dense,
+ * class-diverse run and trips the gate. A `-`-free candidate is a single
+ * segment, i.e. byte-identical to the pre-fix whole-run check.
+ */
 function looksHighEntropySecret(value) {
+    return value.split("-").some(isOpaqueSecretRun);
+}
+/**
+ * True when a delimiter-free run is a dense, character-class-diverse opaque
+ * secret: an entropy floor AND ≥2 character classes, and either a digit or an
+ * extreme length. The digit/length clause keeps digit-free mixed-case
+ * identifiers (stack-trace frames, API symbol names the diagnostic bundle
+ * captures) legible while real secret shapes still match. A segment below ~8
+ * chars cannot clear the entropy floor, so dictionary words and short slug parts
+ * fall out on entropy alone — no separate length gate needed here (the
+ * ≥24-char {@link HIGH_ENTROPY_CANDIDATE} bounds the whole candidate).
+ */
+function isOpaqueSecretRun(value) {
     if (charClassCount(value) < MIN_CHAR_CLASSES)
         return false;
     if (shannonEntropyBits(value) < ENTROPY_BITS_PER_CHAR)
         return false;
-    // Require a digit OR extreme length so digit-free mixed-case identifiers
-    // (stack-trace frames, API symbol names) are not destroyed in diagnostic
-    // output, while real secret shapes (alnum-mixed, or very long) still match.
     return /[0-9]/.test(value) || value.length >= HIGH_ENTROPY_NO_DIGIT_MIN_LEN;
 }
 /** How many of {lowercase, uppercase, digit} appear in `value` (0–3). */

package/dist/_contracts/stable.d.ts

@@ -22,5 +22,19 @@
  * exact default API plane.
  */
 export declare const AEX_DEFAULT_BASE_URL = "https://api.aex.dev";
+/**
+ * Plane → API base URL. When the SDK constructor is given no explicit `baseUrl`
+ * it DERIVES the target from the API key's embedded plane (see
+ * {@link import("./api-key.js").parseApiKey}) rather than blindly defaulting to
+ * prod — so a dev key never silently 401s against `api.aex.dev`.
+ *
+ * `prd` is {@link AEX_DEFAULT_BASE_URL}. `dev` is `null`: the dev plane has no
+ * stable public hostname yet, so a dev key still requires an explicit `baseUrl`
+ * — but the plane-mismatch guard (dev key + prd baseUrl) still fires.
+ */
+export declare const PLANE_BASE_URLS: {
+    readonly dev: null;
+    readonly prd: "https://api.aex.dev";
+};
 export declare function stableStringify(value: unknown): string;
 export declare function sha256(value: unknown): string;

package/dist/_contracts/stable.js

@@ -23,6 +23,20 @@ import { createHash } from "node:crypto";
  * exact default API plane.
  */
 export const AEX_DEFAULT_BASE_URL = "https://api.aex.dev";
+/**
+ * Plane → API base URL. When the SDK constructor is given no explicit `baseUrl`
+ * it DERIVES the target from the API key's embedded plane (see
+ * {@link import("./api-key.js").parseApiKey}) rather than blindly defaulting to
+ * prod — so a dev key never silently 401s against `api.aex.dev`.
+ *
+ * `prd` is {@link AEX_DEFAULT_BASE_URL}. `dev` is `null`: the dev plane has no
+ * stable public hostname yet, so a dev key still requires an explicit `baseUrl`
+ * — but the plane-mismatch guard (dev key + prd baseUrl) still fires.
+ */
+export const PLANE_BASE_URLS = {
+    dev: null,
+    prd: AEX_DEFAULT_BASE_URL
+};
 export function stableStringify(value) {
     return JSON.stringify(sortValue(value));
 }

package/dist/_contracts/status.d.ts

@@ -1,7 +1,34 @@
 export declare const RUN_STATUSES: readonly ["queued", "claiming", "provisioning", "session_created", "dispatched", "provider_running", "provider_idle", "provider_rescheduled", "idle", "suspending", "suspended", "deleting", "deleted", "expired", "cancelling", "capturing_outputs", "cleaning_up", "succeeded", "failed", "timed_out", "cancelled", "cleanup_failed"];
 export type RunStatus = typeof RUN_STATUSES[number];
-export declare const SESSION_STATUSES: readonly ["creating", "running", "idle", "suspending", "suspended", "cancelling", "deleting", "deleted", "expired", "error"];
+/**
+ * The RESUMABLE / in-flight lifecycle half of a session's status. A session
+ * whose status is one of these is either transitioning or parked resumable
+ * (`idle`/`suspended`) — it is NOT a terminal outcome. The terminal outcome
+ * half is {@link SESSION_TERMINAL_OUTCOMES}, derived from the run outcome SSoT.
+ */
+export declare const SESSION_LIFECYCLE_STATUSES: readonly ["creating", "running", "idle", "suspending", "suspended", "cancelling", "deleting", "deleted", "expired"];
+export type SessionLifecycleStatus = typeof SESSION_LIFECYCLE_STATUSES[number];
+/**
+ * The terminal OUTCOME half of a session's status — DERIVED from the run
+ * outcome SSoT via `satisfies readonly RunTerminalOutcome[]`, so a new run
+ * outcome fails to compile until it is accounted for here (and therefore in
+ * {@link SESSION_STATUSES}). This is the compile-time binding that stops the
+ * session and run terminal vocabularies from drifting: the bare session
+ * `error` is gone — a failed turn is `failed`, a wall-clock kill `timed_out`,
+ * a cancel `cancelled`, a clean finish `succeeded`.
+ */
+export declare const SESSION_TERMINAL_OUTCOMES: readonly ["succeeded", "failed", "timed_out", "cancelled"];
+export type SessionTerminalOutcome = typeof SESSION_TERMINAL_OUTCOMES[number];
+/**
+ * The full closed set of session statuses: the resumable lifecycle half, the
+ * terminal-outcome half (bound to {@link RUN_TERMINAL_OUTCOMES}), and the
+ * first-class HITL write-gate `awaiting_approval`. Composed — never
+ * hand-listed — so the outcome vocabulary can only be extended at the run SSoT.
+ */
+export declare const SESSION_STATUSES: readonly ["creating", "running", "idle", "suspending", "suspended", "cancelling", "deleting", "deleted", "expired", "succeeded", "failed", "timed_out", "cancelled", "awaiting_approval"];
 export type SessionStatus = typeof SESSION_STATUSES[number];
+/** True when a session status is terminal (an outcome, or deleted/expired). */
+export declare function isTerminalSessionStatus(status: SessionStatus): boolean;
 export type RunStatusKind = "active" | "terminal";
 export declare const TERMINAL_RUN_STATUSES: readonly ["succeeded", "failed", "timed_out", "cancelled", "deleted", "expired", "cleanup_failed"];
 export declare function isTerminalRunStatus(status: RunStatus): boolean;

package/dist/_contracts/status.js

@@ -22,7 +22,13 @@ export const RUN_STATUSES = [
     "cancelled",
     "cleanup_failed"
 ];
-export const SESSION_STATUSES = [
+/**
+ * The RESUMABLE / in-flight lifecycle half of a session's status. A session
+ * whose status is one of these is either transitioning or parked resumable
+ * (`idle`/`suspended`) — it is NOT a terminal outcome. The terminal outcome
+ * half is {@link SESSION_TERMINAL_OUTCOMES}, derived from the run outcome SSoT.
+ */
+export const SESSION_LIFECYCLE_STATUSES = [
     "creating",
     "running",
     "idle",
@@ -31,9 +37,48 @@ export const SESSION_STATUSES = [
     "cancelling",
     "deleting",
     "deleted",
-    "expired",
-    "error"
+    "expired"
 ];
+/**
+ * The terminal OUTCOME half of a session's status — DERIVED from the run
+ * outcome SSoT via `satisfies readonly RunTerminalOutcome[]`, so a new run
+ * outcome fails to compile until it is accounted for here (and therefore in
+ * {@link SESSION_STATUSES}). This is the compile-time binding that stops the
+ * session and run terminal vocabularies from drifting: the bare session
+ * `error` is gone — a failed turn is `failed`, a wall-clock kill `timed_out`,
+ * a cancel `cancelled`, a clean finish `succeeded`.
+ */
+export const SESSION_TERMINAL_OUTCOMES = [
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled"
+];
+/**
+ * The full closed set of session statuses: the resumable lifecycle half, the
+ * terminal-outcome half (bound to {@link RUN_TERMINAL_OUTCOMES}), and the
+ * first-class HITL write-gate `awaiting_approval`. Composed — never
+ * hand-listed — so the outcome vocabulary can only be extended at the run SSoT.
+ */
+export const SESSION_STATUSES = [
+    ...SESSION_LIFECYCLE_STATUSES,
+    ...SESSION_TERMINAL_OUTCOMES,
+    "awaiting_approval"
+];
+/**
+ * The terminal session statuses: the four outcomes plus the lifecycle-terminal
+ * `deleted`/`expired`. `idle`/`suspended` are resumable (NOT terminal) and
+ * `awaiting_approval` is a held gate (NOT terminal).
+ */
+const SESSION_TERMINAL_STATUSES = new Set([
+    ...SESSION_TERMINAL_OUTCOMES,
+    "deleted",
+    "expired"
+]);
+/** True when a session status is terminal (an outcome, or deleted/expired). */
+export function isTerminalSessionStatus(status) {
+    return SESSION_TERMINAL_STATUSES.has(status);
+}
 export const TERMINAL_RUN_STATUSES = [
     "succeeded",
     "failed",

package/dist/_contracts/submission.d.ts

@@ -275,9 +275,26 @@ export interface PlatformSubmission {
     /**
      * Assistant-output granularity. `buffered` (the default) emits one event per
      * assistant message; `stream` emits the agent's per-token text deltas as they
-     * arrive. Buffered is quieter and cheaper; stream suits live typing UIs.
+     * arrive, THEN a final coalesced block. Streaming is CAPABILITY-GATED: it is
+     * only honored for a streamable provider (see {@link STREAMABLE_SHAPES}) and a
+     * `stream` mode on a non-streamable provider is rejected at parse
+     * ({@link assertStreamableOutputMode}) — no silent downgrade.
      */
     readonly outputMode?: OutputMode;
+    /**
+     * Structured-output policy. `{ kind: 'text' }` (default) is free-form; a
+     * `{ kind: 'json_schema', … }` requests provider-native constrained decode.
+     * The run's typed outcome is then `decoded | refused` — no untyped path yields
+     * a hallucinated object. Fail-closed for a provider lacking the capability.
+     */
+    readonly responseFormat?: ResponseFormat;
+    /**
+     * Declarative HITL write-gate: the platform parks the session
+     * `awaiting_approval` BEFORE dispatching any listed tool, holding for an
+     * `approve()`/`deny()`. Structural — independent of model prose. Empty/absent
+     * ⇒ no gate.
+     */
+    readonly approvalGate?: ApprovalGate;
     /**
      * Platform-injection controls. The platform prepends a small system
      * prompt (see `platformSystemPrompt`) ahead of `system` to explain
@@ -391,6 +408,15 @@ export interface RunLimits {
      * single source of truth for that wire→boot name mapping.
      */
     readonly maxSpendUsd?: number;
+    /**
+     * Maximum number of agent ITERATIONS (turns) the run may take before the
+     * platform parks it terminal. A positive integer; omitted ⇒ the platform
+     * default (`RUN_DEFAULT_MAX_TURNS`). Previously a bare server literal absent
+     * from both the public contract and the limits SSoT — now a settable dial.
+     * Only shape/positivity are validated here; clamping to the ceiling is the
+     * resolver's job.
+     */
+    readonly maxTurns?: number;
 }
 /**
  * Per-run machine/capacity intent. v1 exposes only `spot`: opt the run into
@@ -504,6 +530,54 @@ export declare function parseSubmission(input: unknown, options?: {
 export declare const OUTPUT_MODES: readonly ["buffered", "stream"];
 export type OutputMode = (typeof OUTPUT_MODES)[number];
 export declare const DEFAULT_OUTPUT_MODE: OutputMode;
+/**
+ * The provider wire-SHAPES that have a real per-token streaming producer. This
+ * const is the contracts-side SSoT, pinned EQUAL to the platform's shape SSoT by
+ * a cross-repo parity test so streaming can never be promised for a shape
+ * nothing feeds.
+ */
+export declare const STREAMABLE_SHAPES: readonly ["anthropic", "openai_chat"];
+export type StreamableShape = (typeof STREAMABLE_SHAPES)[number];
+/** True when a provider has a streaming producer wired (a {@link STREAMABLE_SHAPES} shape). */
+export declare function isStreamableProvider(provider: RunProvider): boolean;
+/**
+ * Fail-closed streaming gate: `outputMode:'stream'` on a NON-streamable provider
+ * throws (a HARD reject — no silent downgrade to buffered). Called by
+ * {@link parseRunSubmissionRequest} once mode + provider are both known.
+ */
+export declare function assertStreamableOutputMode(outputMode: OutputMode | undefined, provider: RunProvider): void;
+/** Response-format kinds: free-form `text` (default) or provider-native `json_schema`. */
+export declare const RESPONSE_FORMAT_KINDS: readonly ["text", "json_schema"];
+export type ResponseFormatKind = (typeof RESPONSE_FORMAT_KINDS)[number];
+/**
+ * Structured-output policy. `{ kind: 'text' }` is free-form; `{ kind:
+ * 'json_schema', schema, strict?, name? }` requests provider-native constrained
+ * decode against `schema` (a JSON Schema object).
+ */
+export type ResponseFormat = {
+    readonly kind: "text";
+} | {
+    readonly kind: "json_schema";
+    readonly schema: JsonValue;
+    readonly strict?: boolean;
+    readonly name?: string;
+};
+/**
+ * Parse the optional `submission.responseFormat`. Mirrors {@link parseOutputMode}
+ * / {@link OUTPUT_MODES}: absent ⇒ undefined; a bad `kind` or unknown subfield is
+ * rejected (fail-fast). `json_schema` requires a JSON-object `schema`.
+ */
+export declare function parseResponseFormat(input: unknown): ResponseFormat | undefined;
+/** Declarative HITL write-gate: park `awaiting_approval` before any listed tool. */
+export interface ApprovalGate {
+    readonly tools: readonly string[];
+}
+/**
+ * Parse the optional `submission.approvalGate`. Absent / empty tool list ⇒
+ * undefined (no gate). Tool names are deduped; the strict allow-list mirrors the
+ * sibling parsers.
+ */
+export declare function parseApprovalGate(input: unknown): ApprovalGate | undefined;
 /**
  * The CLOSED set of builtin tool NAMES the managed runtime can inject — one per
  * machine tool the hands implement. This list is the single source of truth for
@@ -515,7 +589,7 @@ export declare const DEFAULT_OUTPUT_MODE: OutputMode;
  * Order mirrors `HANDS_TOOLS`. A builtin tool reference (a bare string in
  * `submission.tools`) must be a member of this set.
  */
-export declare const BUILTIN_TOOL_NAMES: readonly ["bash", "read_file", "write_file", "edit_file", "grep", "glob", "head", "tail", "todo_write", "subagent", "subagent_result", "web_fetch", "web_search", "bash_output", "bash_kill", "code_execution", "wait", "git"];
+export declare const BUILTIN_TOOL_NAMES: readonly ["bash", "read_file", "write_file", "edit_file", "grep", "glob", "head", "tail", "todo_write", "subagent", "subagent_result", "web_fetch", "web_search", "bash_output", "bash_kill", "code_execution", "wait", "git", "ls", "stat", "wc"];
 export type BuiltinToolName = (typeof BUILTIN_TOOL_NAMES)[number];
 /**
  * Typo-safe accessors for the closed builtin tool set: each key maps to the
@@ -545,6 +619,9 @@ export declare const BuiltinTools: {
     readonly code_execution: "code_execution";
     readonly wait: "wait";
     readonly git: "git";
+    readonly ls: "ls";
+    readonly stat: "stat";
+    readonly wc: "wc";
 };
 /**
  * The default builtin tool set injected when `includeBuiltinTools !== false`.

package/dist/_contracts/submission.js

@@ -565,6 +565,9 @@ export function parseRunSubmissionRequest(input, options = {}) {
         trustedReparse: options.trustedReparse === true
     });
     assertRunModelMatchesProvider(provider, submission.model);
+    // Fail-closed streaming: `outputMode:'stream'` on a non-streamable provider is
+    // a hard reject at parse time (no silent downgrade).
+    assertStreamableOutputMode(submission.outputMode, provider);
     crossValidateSecretEnvAndValues(submission.secretEnv, secrets.envSecrets);
     // mcpServers names must agree across the submission half and the
     // secrets half — every secrets.mcpServers[i].name MUST resolve to a
@@ -648,7 +651,7 @@ export function parseRunLimits(input) {
         return undefined;
     }
     const value = requireRecord(input, "limits");
-    const allowed = new Set(["maxConcurrentChildRuns", "maxSubagentDepth", "maxSpendUsd"]);
+    const allowed = new Set(["maxConcurrentChildRuns", "maxSubagentDepth", "maxSpendUsd", "maxTurns"]);
     for (const key of Object.keys(value)) {
         if (!allowed.has(key)) {
             throw new Error(`limits.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
@@ -660,16 +663,23 @@ export function parseRunLimits(input) {
     // NUMBER, not a positive int. Clamping to the workspace/platform ceiling is the
     // resolver's job; here we only enforce shape + positivity.
     const maxSpendUsd = optionalPositiveNumber(value.maxSpendUsd, "limits.maxSpendUsd");
+    // maxTurns is an ITERATION count — a positive safe integer. Clamp to the ceiling
+    // is the resolver's job; here we enforce shape + positivity only.
+    const maxTurns = optionalPositiveInt(value.maxTurns, "limits.maxTurns");
     // Collapse an all-absent override (e.g. `limits: {}`) to `undefined` so it never
     // lands an empty object on the request — matches sibling parsers (parseRunWebhook,
     // parseEnvironment). The resolver supplies platform defaults for absent fields.
-    if (maxConcurrentChildRuns === undefined && maxSubagentDepth === undefined && maxSpendUsd === undefined) {
+    if (maxConcurrentChildRuns === undefined &&
+        maxSubagentDepth === undefined &&
+        maxSpendUsd === undefined &&
+        maxTurns === undefined) {
         return undefined;
     }
     return {
         ...(maxConcurrentChildRuns !== undefined ? { maxConcurrentChildRuns } : {}),
         ...(maxSubagentDepth !== undefined ? { maxSubagentDepth } : {}),
-        ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {})
+        ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {}),
+        ...(maxTurns !== undefined ? { maxTurns } : {})
     };
 }
 /**
@@ -766,6 +776,8 @@ export function parseSubmission(input, options = {}) {
         "outputs",
         "includeBuiltinTools",
         "outputMode",
+        "responseFormat",
+        "approvalGate",
         "platform"
     ]);
     for (const key of Object.keys(value)) {
@@ -789,6 +801,8 @@ export function parseSubmission(input, options = {}) {
     const outputs = parseOutputs(value.outputs);
     const includeBuiltinTools = parseIncludeBuiltinTools(value.includeBuiltinTools);
     const outputMode = parseOutputMode(value.outputMode);
+    const responseFormat = parseResponseFormat(value.responseFormat);
+    const approvalGate = parseApprovalGate(value.approvalGate);
     const platform = parsePlatformConfig(value.platform);
     return {
         model,
@@ -808,6 +822,8 @@ export function parseSubmission(input, options = {}) {
         ...(includeBuiltinTools !== undefined ? { includeBuiltinTools } : {}),
         ...(builtinTools.length > 0 ? { builtinTools } : {}),
         ...(outputMode !== undefined ? { outputMode } : {}),
+        ...(responseFormat !== undefined ? { responseFormat } : {}),
+        ...(approvalGate !== undefined ? { approvalGate } : {}),
         ...(platform ? { platform } : {})
     };
 }
@@ -869,6 +885,127 @@ function parseOutputMode(input) {
     }
     return input;
 }
+// ---------------------------------------------------------------------------
+// Streaming capability model — WS9. `outputMode:'stream'` is capability-gated.
+// ---------------------------------------------------------------------------
+/**
+ * The provider wire-SHAPES that have a real per-token streaming producer. This
+ * const is the contracts-side SSoT, pinned EQUAL to the platform's shape SSoT by
+ * a cross-repo parity test so streaming can never be promised for a shape
+ * nothing feeds.
+ */
+export const STREAMABLE_SHAPES = ["anthropic", "openai_chat"];
+/**
+ * Each provider's wire shape, or `null` when it has no streaming producer wired
+ * yet. `stream` output is only honored for a provider whose shape is streamable.
+ */
+const PROVIDER_STREAM_SHAPE = {
+    anthropic: "anthropic",
+    deepseek: "openai_chat",
+    openai: "openai_chat",
+    gemini: null,
+    mistral: "openai_chat",
+    openrouter: "openai_chat",
+    doubao: "openai_chat",
+    "doubao-cn": "openai_chat"
+};
+/** True when a provider has a streaming producer wired (a {@link STREAMABLE_SHAPES} shape). */
+export function isStreamableProvider(provider) {
+    return PROVIDER_STREAM_SHAPE[provider] !== null;
+}
+function streamableProviders() {
+    return Object.keys(PROVIDER_STREAM_SHAPE).filter(isStreamableProvider);
+}
+/**
+ * Fail-closed streaming gate: `outputMode:'stream'` on a NON-streamable provider
+ * throws (a HARD reject — no silent downgrade to buffered). Called by
+ * {@link parseRunSubmissionRequest} once mode + provider are both known.
+ */
+export function assertStreamableOutputMode(outputMode, provider) {
+    if (outputMode === "stream" && !isStreamableProvider(provider)) {
+        throw new Error(`submission.outputMode 'stream' is not supported for provider ${provider}; ` +
+            `streaming is available for: ${streamableProviders().join(", ")}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Structured-output (schema-decode) policy — WS10.
+// ---------------------------------------------------------------------------
+/** Response-format kinds: free-form `text` (default) or provider-native `json_schema`. */
+export const RESPONSE_FORMAT_KINDS = ["text", "json_schema"];
+/**
+ * Parse the optional `submission.responseFormat`. Mirrors {@link parseOutputMode}
+ * / {@link OUTPUT_MODES}: absent ⇒ undefined; a bad `kind` or unknown subfield is
+ * rejected (fail-fast). `json_schema` requires a JSON-object `schema`.
+ */
+export function parseResponseFormat(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    const value = requireRecord(input, "submission.responseFormat");
+    const kind = value.kind;
+    if (typeof kind !== "string" || !RESPONSE_FORMAT_KINDS.includes(kind)) {
+        throw new Error(`submission.responseFormat.kind must be one of ${RESPONSE_FORMAT_KINDS.join(", ")}`);
+    }
+    if (kind === "text") {
+        for (const key of Object.keys(value)) {
+            if (key !== "kind") {
+                throw new Error(`submission.responseFormat.${key} is not allowed when kind is 'text'`);
+            }
+        }
+        return { kind: "text" };
+    }
+    const allowed = new Set(["kind", "schema", "strict", "name"]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new Error(`submission.responseFormat.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
+        }
+    }
+    if (!isRecord(value.schema) || !isJsonValue(value.schema)) {
+        throw new Error("submission.responseFormat.schema must be a JSON-serializable object");
+    }
+    const schema = value.schema;
+    if (value.strict !== undefined && typeof value.strict !== "boolean") {
+        throw new Error("submission.responseFormat.strict must be a boolean");
+    }
+    const name = optionalString(value.name, "submission.responseFormat.name");
+    return {
+        kind: "json_schema",
+        schema,
+        ...(value.strict !== undefined ? { strict: value.strict } : {}),
+        ...(name !== undefined ? { name } : {})
+    };
+}
+/**
+ * Parse the optional `submission.approvalGate`. Absent / empty tool list ⇒
+ * undefined (no gate). Tool names are deduped; the strict allow-list mirrors the
+ * sibling parsers.
+ */
+export function parseApprovalGate(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    const value = requireRecord(input, "submission.approvalGate");
+    for (const key of Object.keys(value)) {
+        if (key !== "tools") {
+            throw new Error(`submission.approvalGate.${key} is not an allowed field; permitted: tools`);
+        }
+    }
+    if (!Array.isArray(value.tools)) {
+        throw new Error("submission.approvalGate.tools must be an array of tool names");
+    }
+    const seen = new Set();
+    const tools = [];
+    value.tools.forEach((entry, index) => {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new Error(`submission.approvalGate.tools[${index}] must be a non-empty string`);
+        }
+        if (!seen.has(entry)) {
+            seen.add(entry);
+            tools.push(entry);
+        }
+    });
+    if (tools.length === 0)
+        return undefined;
+    return { tools };
+}
 /**
  * The CLOSED set of builtin tool NAMES the managed runtime can inject — one per
  * machine tool the hands implement. This list is the single source of truth for
@@ -898,7 +1035,10 @@ export const BUILTIN_TOOL_NAMES = [
     "bash_kill",
     "code_execution",
     "wait",
-    "git"
+    "git",
+    "ls",
+    "stat",
+    "wc"
 ];
 /**
  * Typo-safe accessors for the closed builtin tool set: each key maps to the
@@ -927,7 +1067,10 @@ export const BuiltinTools = {
     bash_kill: "bash_kill",
     code_execution: "code_execution",
     wait: "wait",
-    git: "git"
+    git: "git",
+    ls: "ls",
+    stat: "stat",
+    wc: "wc"
 };
 /**
  * The default builtin tool set injected when `includeBuiltinTools !== false`.

package/dist/_contracts/suggest.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared "did you mean?" suggester — the SSoT for near-miss enum hints across
+ * the SDK and the CLI. Previously this lived only in the CLI, so the SDK could
+ * not emit a fuzzy model/provider hint even though the docs promised one.
+ */
+/**
+ * The closest candidate to `input` by a unique case-insensitive prefix match,
+ * else by Levenshtein distance (≤ 2), else `undefined`. Ties break by
+ * declaration order. Used on an invalid `--model` / `--provider` /
+ * `--runtime-size` (and the SDK's unknown-model throw) to turn a flat rejection
+ * into a fix hint.
+ */
+export declare function suggest(input: string, candidates: readonly string[]): string | undefined;
+/** Levenshtein edit distance between two strings (rolling two-row DP). */
+export declare function levenshtein(a: string, b: string): number;