@aexhq/sdk 0.39.0 → 0.40.0

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-a2adb1e75358c6a3672cea88be6b784ad981ff9ae32b14f31d5e0dd2712cbaea  cli.mjs
+8897a441b79fa1dff980a75c03cb387f105f4583a6139eb47787de30ab77e1d6  cli.mjs

package/dist/client.d.ts

@@ -1,7 +1,7 @@
-import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type BillingCheckoutRequest, type BillingHostedSession, type BillingLedgerPage, type BillingLedgerQuery, type BillingPortalRequest, type BillingSummary, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputFileType, type OutputLink, type OutputLinkOptions, type OutputQuery, type OutputText, type OutputMode, type ReadOutputTextOptions, type OutputSearchQuery, type OutputSearchPage, type Session, type SessionCreateRequest, type SessionEvent, type SessionListPage, type SessionListQuery, type SessionMessage, type SessionStateChangeAccepted, type SessionTurn, type PlatformEnvironmentInput, type PlatformSubmission, type Run, type RunModel, type RunEvent, type RunTrace, type UsageSummary, type RunWebhookDelivery, type RunProvider, type SecretRecord, type RunUnit, type BuiltinToolName, type RuntimeSize, type SkillRecord, type WebhookSigningSecret, type WebSocketFactory, type WhoAmI } from "./_contracts/index.js";
+import { HttpClient, SecretString, type AexEventView, type AgentsMdRecord, type ApprovalGate, type BatchResult, type BillingCheckoutRequest, type BillingHostedSession, type BillingLedgerPage, type BillingLedgerQuery, type BillingPortalRequest, type BillingSummary, type ChildRunRef, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputFileType, type OutputLink, type OutputLinkOptions, type OutputQuery, type OutputText, type OutputMode, type ReadOutputTextOptions, type ResponseFormat, type OutputSearchQuery, type OutputSearchPage, type RunOutcome, type Session, type SessionCreateRequest, type SessionListPage, type SessionListQuery, type SessionMessage, type SessionStateChangeAccepted, type SessionTerminalOutcome, type SessionTurn, type SettledResult, type PlatformEnvironmentInput, type PlatformSubmission, type Run, type RunModel, type RunTrace, type RunWebhookDelivery, type RunProvider, type SecretRecord, type RunUnit, type BuiltinToolName, type RuntimeSize, type SkillRecord, type WebhookSigningSecret, type WebSocketFactory, type WhoAmI } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { type UploadedAsset } from "./asset-upload.js";
-import { File } from "./file.js";
+import { File, type ZipStreamDriver } from "./file.js";
 import { McpServer } from "./mcp-server.js";
 import { type RetryOptions } from "./retry.js";
 import { Secret } from "./secret.js";
@@ -36,48 +36,47 @@ export interface AexOptions {
     readonly retry?: RetryOptions | false;
 }
 /**
- * The settle-consistent result of {@link Aex.run}:
- * the one-shot session record plus its events, decoded trace, assistant text,
- * and captured outputs — everything a "do it and give me the result" caller
- * needs without hand-rolling a session/message/stream loop.
+ * The unified SETTLED result of {@link Aex.run}. Extends the contracts
+ * {@link SettledResult} (the ONE settled shape `run()` and `done()` share), so
+ * the terminal `status` (a {@link SessionTerminalOutcome}), `ok`, `costUsd`
+ * (`number`, `>= 0`), and `usage` are ALWAYS present — `run()` awaits the settle
+ * commit by default. Adds the one-shot conveniences: the run-compatible record,
+ * events, decoded trace, assistant text, and captured outputs.
+ *
+ * `T` is the `responseFormat` decode type: when the run was submitted with a
+ * `json_schema` `responseFormat`, {@link outcome} carries the typed decoded
+ * value or a typed refusal.
  */
-export interface RunResult {
+export interface RunResult<T = unknown> extends SettledResult {
     readonly runId: string;
     /** The session id used as the run-compatible handle. */
     readonly sessionId?: string;
     /** Run-compatible view of the underlying session record. */
     readonly run: Run;
-    /** The underlying resumable session record. */
+    /** The underlying resumable session record (its lifecycle `status` is idle/suspended when resumable). */
     readonly session?: Session;
     /** The turn accepted for this one-shot run. */
     readonly turn?: SessionTurn;
-    readonly status: string;
-    /** `true` when the one-shot turn parked the session cleanly (`idle` or `suspended`). */
-    readonly ok: boolean;
     /** The assistant's final text. */
     readonly text: string;
     /** Assistant messages projected from the settled event stream. */
     readonly messages: readonly Message[];
-    /** The session turn event stream. */
-    readonly events: readonly RunEvent[];
+    /** The session turn event stream — each event carries the `is*()` type-guard methods. */
+    readonly events: readonly AexEventView[];
     /** Decoded view of the events: tool calls + usage + assistant text. */
     readonly trace: RunTrace;
     /** The run's captured output files. */
     readonly outputs: readonly Output[];
-    /** Aggregate token usage when the deployment exposes it on the record. */
-    readonly usage?: UsageSummary;
     /**
-     * Settle-time showback estimate (USD), from the settle-stamped session
-     * record's `costUsd` (the full `costTelemetry` block is served on
-     * `GET /api/runs/:id`, not on the session projection). The settle
-     * write lands tens of seconds AFTER the turn parks, so by default this is
-     * usually absent on a fresh run — pass `settleConsistent: true` to wait for
-     * it, or read `sessions.get(runId).costUsd` later.
+     * The typed schema-decode outcome — present only when the run was submitted
+     * with a `json_schema` `responseFormat`: `{ kind:'decoded', value }` or
+     * `{ kind:'refused', reason }`. There is no untyped path that yields a
+     * hallucinated object.
      */
-    readonly costUsd?: number;
-    /** The run's error message when `!ok`. */
-    readonly error?: string;
+    readonly outcome?: RunOutcome<T>;
 }
+/** How a one-shot / turn resolves: at the render-complete park, or (default) at the settle commit. */
+export type SettleAwait = "park" | "settle";
 /** Options for {@link Aex.run}. */
 export interface RunCollectOptions {
     /** Overall wait budget (ms) for the one-shot session turn to park. */
@@ -88,13 +87,25 @@ export interface RunCollectOptions {
     /** Throw a {@link RunStateError} when the run does not succeed. Default false. */
     readonly throwOnFailure?: boolean;
     /**
-     * Wait (bounded, ~60s) for the settle write after the turn parks, so the
-     * result carries the settle-stamped `costUsd`/`usage`/`errorMessage`. The
-     * settle lambda lands tens of seconds after the park event, so this trades
-     * latency for a complete record. Default false: return at park; read
-     * `sessions.get(runId)` later for the showback.
+     * When the result resolves. `'settle'` (DEFAULT) waits (bounded) for the
+     * settle commit after the turn parks, so `costUsd`/`usage`/terminal `status`
+     * are always present. `'park'` returns at the render-complete park event for
+     * latency-sensitive streaming — cost/usage are then best-effort (the settle
+     * write lands tens of seconds later).
      */
-    readonly settleConsistent?: boolean;
+    readonly await?: SettleAwait;
+}
+/** The result of {@link Aex.submit}: the run id + a resumable session handle. */
+export interface SubmitResult {
+    readonly runId: string;
+    readonly session: SessionHandle;
+}
+/** Options for {@link Aex.batch}. */
+export interface BatchOptions {
+    /** Max concurrent items, clamped to `[1, 10]` (below the workspace tier cap). */
+    readonly concurrency?: number;
+    /** Reserved — the cost/usage rollup is always computed on the result. */
+    readonly rollup?: boolean;
 }
 export type SessionInput = string | readonly string[];
 export interface SessionEnvironmentOptions extends Omit<PlatformEnvironmentInput, "envVars"> {
@@ -105,6 +116,11 @@ export interface SessionOverrides {
     readonly idleTtl?: string;
     readonly timeout?: string;
     readonly maxSpendUsd?: number;
+    /**
+     * Per-run iteration cap (agent loop turns). Defaults + ceiling are enforced
+     * server-side; omit to accept the platform default. A positive integer.
+     */
+    readonly maxTurns?: number;
 }
 /**
  * Options for opening a session (the low-level API) or a one-shot `run`.
@@ -174,10 +190,32 @@ export interface SessionCreateOptions {
      */
     readonly includeBuiltinTools?: boolean;
     /**
-     * Assistant-output granularity. `"buffered"` (default) delivers one event per
-     * assistant message; `"stream"` delivers per-token text deltas.
+     * Assistant-output granularity. `"buffered"` (default) delivers ONE coalesced
+     * `TEXT_MESSAGE_CONTENT` per assistant message. `"stream"` delivers per-token
+     * `TEXT_MESSAGE_CONTENT` DELTAS (each `event.isTextMessage()` with
+     * `event.data.delta === true`) as they arrive — but this is CAPABILITY-GATED:
+     * `"stream"` is only honored for a streamable provider (submitting `"stream"`
+     * against a non-streamable one is rejected at submit, never silently
+     * downgraded). A coalesced final `TEXT_MESSAGE_CONTENT` ALWAYS follows the
+     * deltas, so a buffered consumer sees the same final text either way; deltas
+     * are provisional until that coalesced block.
      */
     readonly outputMode?: OutputMode;
+    /**
+     * Structured-output policy. `{ kind:'text' }` (default) is free-form;
+     * `{ kind:'json_schema', schema, strict?, name? }` requests provider-native
+     * constrained decode against `schema`. The typed outcome is read from
+     * `run<T>()`'s `result.outcome` (`{ kind:'decoded', value }` or
+     * `{ kind:'refused', reason }`) — never an untyped hallucinated object.
+     */
+    readonly responseFormat?: ResponseFormat;
+    /**
+     * Declarative HITL write-gate: the platform parks the session
+     * `awaiting_approval` BEFORE dispatching any tool in `tools`, independent of
+     * model prose. Resume with `session.approve()` or reject with
+     * `session.deny()`.
+     */
+    readonly approvalGate?: ApprovalGate;
     readonly metadata?: PlatformSubmission["metadata"];
     readonly idempotencyKey?: string;
     /** BYOK provider key(s), keyed by provider. */
@@ -205,6 +243,12 @@ export interface SessionSendOptions {
     readonly webSocketFactory?: WebSocketFactory;
     readonly idleTimeoutMs?: number;
     readonly pingIntervalMs?: number;
+    /**
+     * When the turn resolves. `'settle'` (DEFAULT) awaits the settle commit so
+     * `costUsd`/`usage`/terminal `status` are present on the result; `'park'`
+     * returns at the render-complete park event (cost/usage then best-effort).
+     */
+    readonly await?: SettleAwait;
 }
 export interface SessionRunOptions extends SessionCreateOptions {
     readonly message: SessionInput;
@@ -212,22 +256,29 @@ export interface SessionRunOptions extends SessionCreateOptions {
     readonly messageIdempotencyKey?: string;
     readonly stream?: Omit<SessionSendOptions, "idempotencyKey">;
 }
-export interface SessionTurnResult {
+/**
+ * The unified SETTLED result of one turn (`session.send(...).done()`). Extends
+ * the contracts {@link SettledResult}, so `done()` returns the SAME shape as
+ * `run()`: the terminal `status` (a {@link SessionTerminalOutcome}), `ok`,
+ * `costUsd`, and `usage` are always present (the turn awaits settle by default).
+ */
+export interface SessionTurnResult<T = unknown> extends SettledResult {
     readonly sessionId: string;
     readonly session: Session;
     readonly turn: SessionTurn;
-    readonly status: string;
     readonly text: string;
-    readonly events: readonly SessionEvent[];
+    readonly events: readonly AexEventView[];
     readonly outputs: readonly Output[];
     readonly messages: readonly Message[];
+    /** The typed schema-decode outcome when a `json_schema` `responseFormat` was set. */
+    readonly outcome?: RunOutcome<T>;
 }
 export interface SessionRunResult extends SessionTurnResult {
 }
-export declare class SessionTurnStream implements AsyncIterable<SessionEvent> {
+export declare class SessionTurnStream implements AsyncIterable<AexEventView> {
     #private;
-    constructor(run: () => AsyncGenerator<SessionEvent, SessionTurnResult, void>);
-    [Symbol.asyncIterator](): AsyncIterator<SessionEvent>;
+    constructor(run: () => AsyncGenerator<AexEventView, SessionTurnResult, void>);
+    [Symbol.asyncIterator](): AsyncIterator<AexEventView>;
     done(): Promise<SessionTurnResult>;
 }
 type CallableSessionMessages = SessionMessages & (() => SessionMessages);
@@ -244,16 +295,18 @@ export interface SessionMessages {
     first(): Promise<Message | undefined>;
 }
 /**
- * Accessor over the session's event stream (`session.events()`): the buffered
- * `SessionEvent` snapshots, the polling `RunEvent` iterator, the live
- * coordinator envelope iterator, and the events-namespace archive.
+ * Accessor over the session's event stream (`session.events()`). EVERY surface
+ * yields the one canonical {@link AexEventView} (guard-bearing, non-optional
+ * populated `sequence`): the buffered snapshot `list()`, the polling `stream()`
+ * iterator, the live coordinator `streamEnvelopes()` iterator, and the
+ * events-namespace archive.
  */
 export interface SessionEvents {
-    list(): Promise<readonly SessionEvent[]>;
-    last(): Promise<SessionEvent | undefined>;
-    first(): Promise<SessionEvent | undefined>;
-    stream(options?: StreamEventsOptions): AsyncIterable<RunEvent>;
-    streamEnvelopes(options?: StreamEnvelopesOptions): AsyncIterable<AexEvent>;
+    list(): Promise<readonly AexEventView[]>;
+    last(): Promise<AexEventView | undefined>;
+    first(): Promise<AexEventView | undefined>;
+    stream(options?: StreamEventsOptions): AsyncIterable<AexEventView>;
+    streamEnvelopes(options?: StreamEnvelopesOptions): AsyncIterable<AexEventView>;
     archiveLink(options?: OutputLinkOptions): Promise<OutputLink>;
     /** Download the events-namespace archive as a zip. */
     download(options?: OutputDownloadOptions): Promise<Uint8Array>;
@@ -269,11 +322,20 @@ export interface SessionOutputs {
     read(selector: OutputFileSelector, options?: ReadOutputTextOptions): Promise<OutputText>;
     find(query: OutputQuery): Promise<readonly Output[]>;
     findOne(query: OutputQuery): Promise<Output | null>;
+    /**
+     * Search THIS session's captured outputs by filename (`string | RegExp`) /
+     * extension / content type. Metadata-only (reference hits, no bytes). A
+     * content-shaped query throws a typed "content search unsupported" rather than
+     * silently returning 0 hits.
+     */
+    search(query?: PerSessionOutputSearchQuery): Promise<OutputSearchPage>;
     link(selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
     fetch(selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<Response>;
     /** No selector = outputs-namespace zip; with selector = one file's raw bytes. */
     download(selector?: OutputFileSelector, options?: OutputDownloadOptions): Promise<Uint8Array>;
 }
+/** A per-session output search — {@link OutputSearchQuery} without the cross-run `runIds` corpus. */
+export type PerSessionOutputSearchQuery = Omit<OutputSearchQuery, "runIds">;
 /**
  * Accessor over the session's webhook delivery ledger (`session.webhooks()`).
  */
@@ -299,6 +361,24 @@ export declare class SessionHandle {
     cancel(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
     resume(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
     delete(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<void>;
+    /**
+     * Request the HITL write-gate: park this session `awaiting_approval` before
+     * its next gated action. Imperative counterpart to the declarative
+     * `approvalGate` submission option. Resume with {@link approve} / reject with
+     * {@link deny}.
+     */
+    requestApproval(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
+    /** Approve an `awaiting_approval` session so the held turn resumes (→ running). */
+    approve(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
+    /** Deny an `awaiting_approval` session so the held turn is cancelled (→ cancelled). */
+    deny(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
+    /**
+     * Enumerate this run's subagent CHILD runs (`GET /runs/:id/children`). Each is
+     * a {@link ChildRunHandle} backed by the RUN facade (getRun/events/outputs) —
+     * NOT `openSession` — so every child the platform hands you is resolvable, with
+     * its lineage (`parentRunId`/`depth`) and terminal outcome exposed.
+     */
+    children(): Promise<readonly ChildRunHandle[]>;
     /**
      * Accessor for the session's assistant messages. `all()` returns them
      * oldest-first; `last()`/`first()` return a single entry or `undefined` when
@@ -308,7 +388,7 @@ export declare class SessionHandle {
     get messages(): CallableSessionMessages;
     /**
      * Accessor for the session's event stream: the buffered `SessionEvent`
-     * snapshots (`list`/`last`/`first`), the polling `RunEvent` iterator
+     * snapshots (`list`/`last`/`first`), the polling `AexEventView` iterator
      * (`stream`), the live coordinator envelope iterator (`streamEnvelopes`), and
      * the events-namespace archive (`archiveLink`/`download`).
      */
@@ -372,19 +452,70 @@ export declare class SessionClient {
      * live handle share one accessor convention.
      */
     outputs(sessionId: string): SessionOutputs;
-    /**
-     * Find output files across sessions by filename / extension / content type.
-     * Returns lean REFERENCE hits (never bytes; fetch content with `readOutput`).
-     * Scope the search to a corpus with `query.runIds` (a session-id allow-list);
-     * omit it to scan every session in the workspace. Composed client-side (per-
-     * session `listSessionOutputs` + the contracts output filter), bounded by
-     * `query.limit` (default 100).
-     */
-    searchOutputs(query?: OutputSearchQuery): Promise<OutputSearchPage>;
     run(options: SessionRunOptions): Promise<SessionRunResult>;
 }
+/**
+ * Cross-run output search (`aex.outputs`). Composed client-side (per-run
+ * `listSessionOutputs` + the contracts output filter): scope a corpus with
+ * `query.runIds`, or omit it to scan every run in the workspace. Metadata-only
+ * (reference hits, no bytes); a content-shaped query throws a typed
+ * "content search unsupported".
+ */
+export declare class OutputsClient {
+    #private;
+    constructor(http: HttpClient);
+    search(query?: OutputSearchQuery): Promise<OutputSearchPage>;
+}
+/** A run-facade events accessor (list + polling stream) keyed on a run id. */
+export interface RunEvents {
+    list(): Promise<readonly AexEventView[]>;
+    stream(options?: StreamEventsOptions): AsyncIterable<AexEventView>;
+}
+/** A run-facade outputs accessor (a subset of {@link SessionOutputs}) keyed on a run id. */
+export interface RunOutputs {
+    list(query?: OutputQuery): Promise<readonly Output[]>;
+    find(query: OutputQuery): Promise<readonly Output[]>;
+    findOne(query: OutputQuery): Promise<Output | null>;
+    read(selector: OutputFileSelector, options?: ReadOutputTextOptions): Promise<OutputText>;
+    link(selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
+    download(selector?: OutputFileSelector, options?: OutputDownloadOptions): Promise<Uint8Array>;
+}
+/**
+ * A first-class, lineage-discoverable SUBAGENT CHILD run — handed out by
+ * `session.children()` / `run.children()`, backed by the RUN facade
+ * (getRun/events/outputs), NOT `openSession`. Every child the platform hands you
+ * is resolvable through this handle; its lineage (`parentRunId`/`depth`) and
+ * terminal outcome (`status`) are first-class.
+ */
+export declare class ChildRunHandle {
+    #private;
+    constructor(http: HttpClient, ref: ChildRunRef, fetch?: FetchLike);
+    get id(): string;
+    get parentRunId(): string;
+    get depth(): number | undefined;
+    /** The child's run status (a real run terminal outcome once settled). */
+    get status(): string;
+    get ref(): ChildRunRef;
+    /** Re-read the child run record (status, lineage, costTelemetry). */
+    get(): Promise<Run>;
+    /** The child's events over the RUN facade (`/runs/:id/events`). */
+    events(): RunEvents;
+    /** The child's captured outputs over the RUN facade (`/runs/:id/outputs`). */
+    outputs(): RunOutputs;
+    /** This child's own subagent children (recursive lineage). */
+    children(): Promise<readonly ChildRunHandle[]>;
+    /** Cancel the child run (run facade `POST /runs/:id/cancel`). */
+    cancel(): Promise<void>;
+}
+/**
+ * The terminal READ a turn's terminal event carries: either a
+ * {@link SessionTerminalOutcome} (succeeded/failed/timed_out/cancelled) or a
+ * resumable/held lifecycle park (idle/suspended/awaiting_approval). The SDK
+ * READS this from the carried event — it never re-derives a lossy `idle`.
+ */
+export type SessionTerminalRead = SessionTerminalOutcome | "idle" | "suspended" | "awaiting_approval";
 export interface StreamEventsOptions {
-    /** Poll interval in ms for the `RunEvent` snapshot loop. Default 1000. */
+    /** Poll interval in ms for the event snapshot loop. Default 1000. */
     readonly intervalMs?: number;
     readonly signal?: AbortSignal;
 }
@@ -528,6 +659,8 @@ export declare class Aex {
     readonly skills: SkillsClient;
     readonly secrets: SecretsClient;
     readonly sessions: SessionClient;
+    /** Cross-run output search (`aex.outputs.search(...)`). */
+    readonly outputs: OutputsClient;
     constructor(apiKey: string, options?: Omit<AexOptions, "apiKey">);
     constructor(options: AexOptions);
     /**
@@ -555,6 +688,17 @@ export declare class Aex {
         readonly hash: string;
         readonly contentType?: string;
     }): Promise<UploadedAsset>;
+    /**
+     * Internal: materialize a LARGE draft (a `File.fromPath` over the streaming
+     * threshold) to the content store via the two-pass streaming multipart flow —
+     * hash the deterministic canonical-zip stream, presign by hash (dedup still
+     * short-circuits), then upload it in parts. Bounded memory (one entry + one
+     * part). NOT part of the public API.
+     */
+    _uploadAssetStream(args: {
+        readonly drive: ZipStreamDriver;
+        readonly contentType?: string;
+    }): Promise<UploadedAsset>;
     /**
      * Internal: upsert already-uploaded skill metadata into the workspace registry.
      * The bytes are staged through `_uploadAsset`; this call binds the content hash
@@ -575,7 +719,22 @@ export declare class Aex {
      * events, outputs, and session record. The returned `runId` is the session id,
      * so callers can resume later with `openSession(runId)`.
      */
-    run(options: SessionRunOptions, opts?: RunCollectOptions): Promise<RunResult>;
+    run<T = unknown>(options: SessionRunOptions, opts?: RunCollectOptions): Promise<RunResult<T>>;
+    /**
+     * Fire-and-forget: create the session and POST its first turn WITHOUT awaiting
+     * settle (the honest counterpart to await-settle `run()`). Resolves with the
+     * `runId` + a resumable {@link SessionHandle} immediately; observe the run via
+     * a `webhook`, the event stream, or `openSession(runId)`.
+     */
+    submit(options: SessionRunOptions): Promise<SubmitResult>;
+    /**
+     * Run a batch of one-shot items with a bounded worker pool, returning every
+     * item's settled result PLUS a REAL cost/usage rollup. The rollup is honest
+     * because each `run()` awaits settle, so each item's `costUsd`/`usage` is
+     * populated — a failed item lands in `failed[]`, never a silent `$0` success.
+     * Concurrency is clamped below the workspace tier cap.
+     */
+    batch<T = unknown>(items: readonly SessionRunOptions[], options?: BatchOptions): Promise<BatchResult<T>>;
     openSession(options: SessionCreateOptions): Promise<SessionHandle>;
     openSession(sessionId: string): Promise<SessionHandle>;
     /**