@aexhq/sdk 0.39.0 → 0.40.1

package/dist/_contracts/sdk-errors.d.ts

@@ -1,3 +1,4 @@
+import type { AexApiErrorCode } from "./error-codes.js";
 export type AexErrorCode = "RUN_CONFIG_INVALID" | "CREDENTIAL_INVALID" | "PROVIDER_ERROR" | "RUN_STATE_ERROR" | "CLEANUP_ERROR" | "RUNTIME_UNSUPPORTED" | "API_ERROR" | "NETWORK_ERROR";
 export declare class AexError extends Error {
     readonly code: AexErrorCode;
@@ -27,13 +28,69 @@ export declare 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 declare class AexApiError extends AexError {
     readonly status: number;
     readonly body: unknown;
-    constructor(status: number, message: string, body: unknown);
+    /** The server's stable error code, when the body carried a known one. */
+    readonly apiCode: AexApiErrorCode | undefined;
+    /** Request id (body `requestId` or a response header) for support correlation. */
+    readonly requestId: string | undefined;
+    constructor(status: number, message: string, body: unknown, options?: {
+        readonly apiCode?: AexApiErrorCode | undefined;
+        readonly requestId?: string | undefined;
+        readonly cause?: unknown;
+    });
+}
+/** Shared construction shape for the typed {@link AexApiError} subclasses. */
+export interface AexApiErrorInit {
+    readonly status: number;
+    readonly message: string;
+    readonly body: unknown;
+    readonly apiCode?: AexApiErrorCode | undefined;
+    readonly requestId?: string | undefined;
+    readonly cause?: unknown;
+}
+/** 401/403 auth failure (token invalid/revoked/expired, forbidden, insufficient scope). */
+export declare class AexAuthError extends AexApiError {
+    /** The scope the endpoint required, when the server named it (insufficient_scope). */
+    readonly requiredScope: string | undefined;
+    constructor(init: AexApiErrorInit & {
+        readonly requiredScope?: string | undefined;
+    });
+}
+/** 409 — the idempotency key was reused with a different request body. */
+export declare class AexIdempotencyConflictError extends AexApiError {
+    constructor(init: AexApiErrorInit);
+}
+/** 404 — the requested resource was not found. */
+export declare class AexNotFoundError extends AexApiError {
+    constructor(init: AexApiErrorInit);
+}
+/** 429 — the workspace hit a rate/concurrency limit; retry after a backoff. */
+export declare class AexRateLimitError extends AexApiError {
+    /** Suggested backoff (ms), when the server advertised one (Retry-After). */
+    readonly retryAfterMs: number | undefined;
+    constructor(init: AexApiErrorInit & {
+        readonly retryAfterMs?: number | undefined;
+    });
 }
+/** True for a 401/403 authentication/authorization failure. */
+export declare function isAuthError(err: unknown): err is AexAuthError;
+/** True for a 403 whose cause is a missing scope (`insufficient_scope`). */
+export declare function isInsufficientScope(err: unknown): boolean;
+/** True for a 409 idempotency-key reuse conflict. */
+export declare function isIdempotencyConflict(err: unknown): err is AexIdempotencyConflictError;
+/** True for a 404 not-found error. */
+export declare function isNotFound(err: unknown): err is AexNotFoundError;
+/** True for a 429 rate/concurrency-limit error. */
+export declare function isRateLimited(err: unknown): err is 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
@@ -52,6 +109,8 @@ export declare class AexNetworkError extends AexError {
     readonly causeCode: string | undefined;
     /** Attempts made when a retry layer exhausted its budget; `1` otherwise. */
     readonly attempts: number;
+    /** Total elapsed time (ms) across all attempts, when the retry layer set it. */
+    readonly elapsedMs: number | undefined;
     constructor(args: {
         readonly method: string;
         readonly host: string;

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`.