@aexhq/sdk 0.39.0 → 0.40.1

package/dist/_contracts/models.js

@@ -1,3 +1,4 @@
+import { suggest } from "./suggest.js";
 /**
  * Source of truth for the closed model set: each canonical model id maps to the
  * upstream providers that can serve it and the **provider-native** model string
@@ -149,6 +150,38 @@ export function resolveProviderModelId(model, provider) {
     }
     return native;
 }
+/**
+ * The single model→provider resolver shared by the SDK and the CLI, wrapping
+ * {@link providersForModel} with the forward-compat unknown-model allowance:
+ *
+ *   - `provider` given: it is honored. If `model` is a KNOWN id, the provider
+ *     must serve it (else throw). If `model` is UNKNOWN, it is allowed through
+ *     so a slightly-old client can still run a newly-launched model (the server
+ *     arbitrates).
+ *   - `provider` omitted: a known model resolves to its DEFAULT provider (first
+ *     declared). An UNKNOWN model with no provider throws a `did you mean?`
+ *     hint — you must name a provider to run a model this client doesn't know.
+ *
+ * Returns the resolved {@link RunProvider}.
+ */
+export function resolveModelProvider(model, provider) {
+    const providers = providersForModel(model);
+    if (provider !== undefined) {
+        if (providers.length > 0 && !providers.includes(provider)) {
+            throw new Error(`model ${JSON.stringify(model)} is not available for provider ${provider}; ` +
+                `available: ${providers.join(", ")}`);
+        }
+        return provider;
+    }
+    const inferred = providers[0];
+    if (inferred === undefined) {
+        const hint = suggest(model, RUN_MODELS);
+        throw new Error(`${JSON.stringify(model)} is not a known model id` +
+            (hint ? ` (did you mean ${JSON.stringify(hint)}?)` : "") +
+            "; pass provider explicitly to run it");
+    }
+    return inferred;
+}
 export function isRunModel(input) {
     return typeof input === "string" && RUN_MODELS.includes(input);
 }

package/dist/_contracts/operations.d.ts

@@ -1,6 +1,7 @@
 import type { HttpClient } from "./http.js";
+import type { AexEvent } from "./event-envelope.js";
 import type { RunUnit } from "./run-unit.js";
-import type { AgentsMdRecord, BillingCheckoutRequest, BillingHostedSession, BillingLedgerPage, BillingLedgerQuery, BillingPortalRequest, BillingSummary, FileRecord, Output, OutputLink, OutputLinkOptions, OutputFileDownload, OutputFileSelector, OutputFileType, OutputQuery, OutputText, ReadOutputTextOptions, Run, RunEvent, RunListPage, RunListQuery, Session, SessionCreateRequest, SessionEvent, SessionListPage, SessionListQuery, SessionMessageAccepted, SessionMessageRequest, SessionMessagesPage, SessionMessagesQuery, SessionStateChangeAccepted, RunWebhookDelivery, SecretRecord, SecretReveal, SkillRecord, WebhookSigningSecret, WhoAmI } from "./runtime-types.js";
+import type { AgentsMdRecord, BillingCheckoutRequest, BillingHostedSession, BillingLedgerPage, BillingLedgerQuery, BillingPortalRequest, BillingSummary, ChildRunRef, FileRecord, Output, OutputLink, OutputLinkOptions, OutputFileDownload, OutputFileSelector, OutputFileType, OutputQuery, OutputText, ReadOutputTextOptions, Run, RunListPage, RunListQuery, Session, SessionCreateRequest, SessionEvent, SessionListPage, SessionListQuery, SessionMessageAccepted, SessionMessageRequest, SessionMessagesPage, SessionMessagesQuery, SessionStateChangeAccepted, RunWebhookDelivery, SecretRecord, SecretReveal, SkillRecord, WebhookSigningSecret, WhoAmI } from "./runtime-types.js";
 import type { PlatformRunSubmissionInput } from "./submission.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
@@ -39,7 +40,32 @@ export declare function listRuns(http: HttpClient, query?: RunListQuery): Promis
 export interface IdempotencyOptions {
     readonly idempotencyKey?: string;
 }
+export interface SubmitOptions extends IdempotencyOptions {
+    readonly messageIdempotencyKey?: string;
+}
+/**
+ * Resolve a caller-supplied idempotency key to the value that ships on the
+ * request. FAIL-FAST: an empty or whitespace-only key THROWS
+ * {@link RunConfigValidationError} — a footgun that silently disabled dedup
+ * (`?? generate()` kept `''`, then a downstream truthy header-drop shipped no
+ * `Idempotency-Key`). An absent key generates a fresh one; a real key is
+ * returned verbatim. The single choke point every send/create/run entry uses.
+ */
+export declare function resolveIdempotencyKey(key?: string): string;
 export declare function createSession(http: HttpClient, request: SessionCreateRequest, options?: IdempotencyOptions): Promise<Session>;
+/** The result of a non-blocking {@link submit}: the run id + the created session. */
+export interface SubmitResult {
+    readonly runId: string;
+    readonly session: Session;
+}
+/**
+ * Fire-and-forget submit — create the session and post its first turn WITHOUT
+ * awaiting the turn to settle (the honest counterpart to await-settle `run()`).
+ * Returns the `runId` immediately; observe the run via a `webhook`, the event
+ * stream, or by re-opening the session. Mirrors {@link createSession}'s
+ * idempotency handling.
+ */
+export declare function submit(http: HttpClient, request: SessionCreateRequest, options?: SubmitOptions): Promise<SubmitResult>;
 export declare function getSession(http: HttpClient, sessionId: string): Promise<Session>;
 export declare function listSessions(http: HttpClient, query?: SessionListQuery): Promise<SessionListPage>;
 export declare function sendSessionMessage(http: HttpClient, sessionId: string, request: SessionMessageRequest, options?: IdempotencyOptions): Promise<SessionMessageAccepted>;
@@ -47,6 +73,16 @@ export declare function listSessionMessages(http: HttpClient, sessionId: string,
 export declare function suspendSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
 export declare function cancelSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
 export declare function resumeSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
+/**
+ * Request the HITL write-gate: park the session `awaiting_approval` before its
+ * next gated action (mirrors {@link suspendSession}). Imperative counterpart to
+ * the declarative submission-time `approvalGate`.
+ */
+export declare function requestApproval(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
+/** Approve an `awaiting_approval` session so the held turn resumes (→ running). */
+export declare function approveSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
+/** Deny an `awaiting_approval` session so the held turn is cancelled (→ cancelled). */
+export declare function denySession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
 export declare function deleteSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted | void>;
 export declare function listSessionEvents(http: HttpClient, sessionId: string): Promise<readonly SessionEvent[]>;
 export declare function listSessionOutputs(http: HttpClient, sessionId: string, query?: OutputQuery): Promise<readonly Output[]>;
@@ -57,7 +93,7 @@ export declare function getSessionCoordinatorTicket(http: HttpClient, sessionId:
  * pages and returns the FULL accumulated list, preserving the prior single-call
  * contract for callers (download/*, CLI, streamEvents polling).
  */
-export declare function listRunEvents(http: HttpClient, runId: string): Promise<readonly RunEvent[]>;
+export declare function listRunEvents(http: HttpClient, runId: string): Promise<readonly AexEvent[]>;
 /** A coordinator WS connection grant minted by the hosted API's ticket broker. */
 export interface CoordinatorTicket {
     readonly wsUrl: string;
@@ -94,6 +130,13 @@ export declare const READ_OUTPUT_TEXT_DEFAULT_BYTES = 50000;
  * selector lists the run's outputs to resolve the id; an id selector skips that.
  */
 export declare function readOutputText(http: HttpClient, runId: string, selector: OutputFileSelector, options?: ReadOutputTextOptions): Promise<OutputText>;
+/**
+ * List a run's subagent CHILD runs (`GET /runs/:id/children`). Each row is a
+ * {@link ChildRunRef} whose `id` resolves through the run facade (getRun /
+ * events / outputs) — so every child the platform hands you is resolvable. An
+ * empty array means the run spawned no children.
+ */
+export declare function listRunChildren(http: HttpClient, runId: string): Promise<readonly ChildRunRef[]>;
 export declare function cancelRun(http: HttpClient, runId: string): Promise<void>;
 export declare function deleteRun(http: HttpClient, runId: string): Promise<void>;
 /**
@@ -146,6 +189,14 @@ export declare function getBillingLedger(http: HttpClient, query?: BillingLedger
  */
 export declare function getWebhookSigningSecret(http: HttpClient): Promise<WebhookSigningSecret>;
 export declare function filterOutputs(outputs: readonly Output[], query: OutputQuery): readonly Output[];
+/**
+ * The single filename-matcher for cross-run / per-session output SEARCH. A
+ * string is a case-insensitive SUBSTRING match; a RegExp is tested as given (and
+ * reset to `lastIndex = 0` so a reused `/g` regex is safe). Sharing this SSoT is
+ * what closes the T16 crash class: `searchOutputs` no longer assumes `filename`
+ * is a string and passes a RegExp into `escapeRegExp(...).replace(...)`.
+ */
+export declare function toFilenameMatcher(filename: string | RegExp): (name: string) => boolean;
 export declare function classifyOutput(output: Pick<Output, "filename" | "contentType">): OutputFileType;
 export declare function normalizeOutputLinkExpiresIn(input?: OutputLinkOptions["expiresIn"]): number;
 /**

package/dist/_contracts/operations.js

@@ -1,6 +1,7 @@
 import { strToU8, zipSync } from "fflate";
+import { randomUUID } from "node:crypto";
 import { normalizeRunUnit } from "./run-unit.js";
-import { RunStateError } from "./sdk-errors.js";
+import { RunConfigValidationError, RunStateError } from "./sdk-errors.js";
 import { assertRunRecordArchivePublicSafeV1, buildRunRecordDownloadManifestV1 } from "./run-record.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
@@ -83,8 +84,41 @@ export async function listRuns(http, query) {
     }
     return changed ? { ...page, runs } : page;
 }
+/**
+ * Resolve a caller-supplied idempotency key to the value that ships on the
+ * request. FAIL-FAST: an empty or whitespace-only key THROWS
+ * {@link RunConfigValidationError} — a footgun that silently disabled dedup
+ * (`?? generate()` kept `''`, then a downstream truthy header-drop shipped no
+ * `Idempotency-Key`). An absent key generates a fresh one; a real key is
+ * returned verbatim. The single choke point every send/create/run entry uses.
+ */
+export function resolveIdempotencyKey(key) {
+    if (key === undefined) {
+        return `aex-idem-${randomUUID()}`;
+    }
+    if (typeof key !== "string" || key.trim().length === 0) {
+        throw new RunConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
+            field: "idempotencyKey",
+            value: key
+        });
+    }
+    return key;
+}
+/**
+ * Fail-closed idempotency header builder. An EMPTY string throws (defense in
+ * depth alongside {@link resolveIdempotencyKey}) rather than silently dropping
+ * the header and proceeding non-idempotent; an absent key yields no header.
+ */
 function idempotencyHeaders(options) {
-    return options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : undefined;
+    if (options?.idempotencyKey === undefined)
+        return undefined;
+    if (typeof options.idempotencyKey !== "string" || options.idempotencyKey.trim().length === 0) {
+        throw new RunConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
+            field: "idempotencyKey",
+            value: options.idempotencyKey
+        });
+    }
+    return { "Idempotency-Key": options.idempotencyKey };
 }
 export async function createSession(http, request, options) {
     const headers = idempotencyHeaders(options);
@@ -95,6 +129,36 @@ export async function createSession(http, request, options) {
     });
     return unwrapSession(result);
 }
+/**
+ * Fire-and-forget submit — create the session and post its first turn WITHOUT
+ * awaiting the turn to settle (the honest counterpart to await-settle `run()`).
+ * Returns the `runId` immediately; observe the run via a `webhook`, the event
+ * stream, or by re-opening the session. Mirrors {@link createSession}'s
+ * idempotency handling.
+ */
+export async function submit(http, request, options) {
+    const createKey = resolveIdempotencyKey(options?.idempotencyKey);
+    const messageKey = options?.messageIdempotencyKey !== undefined
+        ? resolveIdempotencyKey(options.messageIdempotencyKey)
+        : `${createKey}:message`;
+    const { input, ...createRequest } = request;
+    assertSubmitInput(input);
+    const created = await createSession(http, createRequest, { idempotencyKey: createKey });
+    const sessionId = created.sessionId ?? created.id;
+    const accepted = await sendSessionMessage(http, sessionId, { input }, { idempotencyKey: messageKey });
+    const session = accepted.session;
+    return { runId: session.sessionId ?? session.id, session };
+}
+function assertSubmitInput(input) {
+    const ok = (typeof input === "string" && input.length > 0) ||
+        (Array.isArray(input) && input.length > 0 && input.every((segment) => typeof segment === "string" && segment.length > 0));
+    if (!ok) {
+        throw new RunConfigValidationError("submit: request.input must be a non-empty string or string array", {
+            field: "input",
+            value: input
+        });
+    }
+}
 export async function getSession(http, sessionId) {
     const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}`);
     return unwrapSession(result);
@@ -141,6 +205,25 @@ export async function resumeSession(http, sessionId, options) {
     const headers = idempotencyHeaders(options);
     return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/resume`, { method: "POST", ...(headers ? { headers } : {}) });
 }
+/**
+ * Request the HITL write-gate: park the session `awaiting_approval` before its
+ * next gated action (mirrors {@link suspendSession}). Imperative counterpart to
+ * the declarative submission-time `approvalGate`.
+ */
+export async function requestApproval(http, sessionId, options) {
+    const headers = idempotencyHeaders(options);
+    return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/request-approval`, { method: "POST", ...(headers ? { headers } : {}) });
+}
+/** Approve an `awaiting_approval` session so the held turn resumes (→ running). */
+export async function approveSession(http, sessionId, options) {
+    const headers = idempotencyHeaders(options);
+    return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/approve`, { method: "POST", ...(headers ? { headers } : {}) });
+}
+/** Deny an `awaiting_approval` session so the held turn is cancelled (→ cancelled). */
+export async function denySession(http, sessionId, options) {
+    const headers = idempotencyHeaders(options);
+    return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/deny`, { method: "POST", ...(headers ? { headers } : {}) });
+}
 export async function deleteSession(http, sessionId, options) {
     const headers = idempotencyHeaders(options);
     return http.request(`/api/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE", ...(headers ? { headers } : {}) });
@@ -212,7 +295,7 @@ export async function findOutput(http, runId, query) {
         return null;
     if (matches.length === 1)
         return matches[0];
-    throw new RunStateError("findOutput: output query matched multiple files", {
+    throw new RunStateError("outputs.findOne: output query matched multiple files", {
         runId,
         matches: matches.map((output) => output.filename ?? output.id)
     });
@@ -260,7 +343,7 @@ export function resolveOutputFileSelector(outputs, selector, runId) {
     if (isPathSelector(selector)) {
         const target = normalizeOutputLookupPath(selector.path);
         if (!target) {
-            throw new RunStateError("downloadOutput: output path must be non-empty", { runId, path: selector.path });
+            throw new RunStateError("outputs.download: output path must be non-empty", { runId, path: selector.path });
         }
         const matches = outputs.filter((output) => {
             if (typeof output.filename !== "string")
@@ -274,15 +357,15 @@ export function resolveOutputFileSelector(outputs, selector, runId) {
         if (matches.length === 1)
             return matches[0];
         if (matches.length > 1) {
-            throw new RunStateError(`downloadOutput: output path "${selector.path}" matched multiple files`, { runId, path: selector.path, matches: matches.map((output) => output.filename ?? output.id) });
+            throw new RunStateError(`outputs.download: output path "${selector.path}" matched multiple files`, { runId, path: selector.path, matches: matches.map((output) => output.filename ?? output.id) });
         }
-        throw new RunStateError(`downloadOutput: output path "${selector.path}" was not found`, {
+        throw new RunStateError(`outputs.download: output path "${selector.path}" was not found`, {
             runId,
             path: selector.path
         });
     }
     if (typeof selector?.id !== "string" || selector.id.length === 0) {
-        throw new RunStateError("downloadOutput: selector must include an output id or path", { runId });
+        throw new RunStateError("outputs.download: selector must include an output id or path", { runId });
     }
     return { ...selector, id: selector.id };
 }
@@ -387,6 +470,18 @@ function grepLines(text, pattern) {
         .filter((line) => test(line))
         .join("\n");
 }
+/**
+ * List a run's subagent CHILD runs (`GET /runs/:id/children`). Each row is a
+ * {@link ChildRunRef} whose `id` resolves through the run facade (getRun /
+ * events / outputs) — so every child the platform hands you is resolvable. An
+ * empty array means the run spawned no children.
+ */
+export async function listRunChildren(http, runId) {
+    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/children`);
+    return Array.isArray(result)
+        ? result
+        : result.children;
+}
 export async function cancelRun(http, runId) {
     await http.request(`/api/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
 }
@@ -522,6 +617,23 @@ function normalizeOutputLookupPath(path) {
 export function filterOutputs(outputs, query) {
     return outputs.filter((output) => outputMatchesQuery(output, query));
 }
+/**
+ * The single filename-matcher for cross-run / per-session output SEARCH. A
+ * string is a case-insensitive SUBSTRING match; a RegExp is tested as given (and
+ * reset to `lastIndex = 0` so a reused `/g` regex is safe). Sharing this SSoT is
+ * what closes the T16 crash class: `searchOutputs` no longer assumes `filename`
+ * is a string and passes a RegExp into `escapeRegExp(...).replace(...)`.
+ */
+export function toFilenameMatcher(filename) {
+    if (typeof filename === "string") {
+        const needle = filename.toLowerCase();
+        return (name) => name.toLowerCase().includes(needle);
+    }
+    return (name) => {
+        filename.lastIndex = 0;
+        return filename.test(name);
+    };
+}
 export function classifyOutput(output) {
     const contentType = normalizeContentType(output.contentType);
     if (contentType) {

package/dist/_contracts/run-record.d.ts

@@ -1,6 +1,7 @@
 import type { RunCostTelemetry } from "./run-cost.js";
 import { type CustodyManifestV1, type CustodyRedactionFinding } from "./run-custody.js";
-import type { Run, RunEvent, Output } from "./runtime-types.js";
+import type { AexEvent } from "./event-envelope.js";
+import type { Run, Output } from "./runtime-types.js";
 import type { PlatformSubmission } from "./submission.js";
 export declare const RUN_RECORD_SCHEMA_VERSION: "aex.run-record.v1";
 export declare const RUN_RECORD_MANIFEST_SCHEMA_VERSION: "aex.run-record.manifest.v1";
@@ -22,7 +23,7 @@ export interface RunRecordMetadataV1 {
 }
 export interface RunRecordEventsV1 {
     /** Typed `channel: "event"` records in the SDK `events/events.jsonl` export. */
-    readonly typed: readonly RunEvent[];
+    readonly typed: readonly AexEvent[];
 }
 export interface RunRecordV1 {
     readonly schemaVersion: typeof RUN_RECORD_SCHEMA_VERSION;

package/dist/_contracts/runtime-types.d.ts

@@ -1,4 +1,5 @@
-import type { SessionStatus } from "./status.js";
+import type { SessionStatus, SessionTerminalOutcome } from "./status.js";
+import type { RunCostProviderUsage } from "./run-cost.js";
 import type { PlatformRunSubmissionInput, PlatformSubmission } from "./submission.js";
 /**
  * Loose record describing a run as the dashboard BFF returns it. Concrete
@@ -37,6 +38,12 @@ export interface Run {
      */
     readonly usage?: UsageSummary;
     readonly costTelemetry?: import("./run-cost.js").RunCostTelemetry;
+    /**
+     * The authoritative terminal OUTCOME of the run's last turn — the settle-
+     * written outcome (`succeeded`/`failed`/`timed_out`/`cancelled`), distinct
+     * from the resumable lifecycle {@link status}. Absent until the run settles.
+     */
+    readonly lastTurnOutcome?: SessionTerminalOutcome;
     readonly runtimeManifest?: import("./runtime-manifest.js").RuntimeManifest;
     readonly [key: string]: unknown;
 }
@@ -68,9 +75,17 @@ export interface Session {
     readonly retainedStorageBytes?: number;
     readonly usage?: UsageSummary;
     readonly costUsd?: number;
+    /**
+     * The authoritative terminal OUTCOME of the session's last turn — the
+     * settle-written outcome (`succeeded`/`failed`/`timed_out`/`cancelled`),
+     * distinct from the resumable lifecycle {@link status} (`idle`/`suspended`).
+     * A cancelled turn reads `cancelled` here even though the session may park
+     * `idle`; absent until the turn settles.
+     */
+    readonly lastTurnOutcome?: SessionTerminalOutcome;
     readonly errorMessage?: string | null;
     /**
-     * Settle-written failure taxonomy for an `error` session (e.g.
+     * Settle-written failure taxonomy for a `failed` session (e.g.
      * `provider-permanent`, `budget_exhausted`) — the class a caller can branch
      * on, complementing the human-readable `errorMessage`.
      */
@@ -158,6 +173,77 @@ export interface UsageSummary {
     readonly cacheCreationInputTokens?: number;
     readonly totalTokens?: number;
 }
+/**
+ * Project a {@link UsageSummary} from the settle-written
+ * {@link RunCostProviderUsage} entries — the SINGLE server source of token
+ * usage ({@link Run.costTelemetry}`.providerUsage`). Sums each field across all
+ * provider entries; a field is present only when at least one entry carried it.
+ * This retires the dead `session.usage` / `aex.usage`-event usage path: the SDK
+ * derives usage from cost telemetry, never re-reads a dual-written top-level
+ * `usage`. Pure.
+ */
+export declare function usageFromProviderUsage(providerUsage: readonly RunCostProviderUsage[] | undefined): UsageSummary;
+/**
+ * The unified SETTLED-RESULT contract shared by `run()` and `done()`. Because
+ * both await the settle commit by default, these fields are ALWAYS present at a
+ * terminal read — they are NON-optional, so a code path that forgets to
+ * populate `costUsd`/`usage`/the terminal `status` fails to typecheck. The SDK
+ * `RunResult`/`SessionTurnResult` extend this one shape so `done()` == `run()`.
+ *
+ * `costUsd` is the AEX showback estimate in USD (>= 0) and EXCLUDES the
+ * customer's BYOK provider spend — price BYOK from `usage` tokens.
+ */
+export interface SettledResult {
+    /** The terminal outcome (never a bare resumable `idle`). */
+    readonly status: SessionTerminalOutcome;
+    /** `succeeded` ⇒ true; `failed`/`timed_out`/`cancelled` ⇒ false. */
+    readonly ok: boolean;
+    /** AEX showback estimate (USD, >= 0). Excludes BYOK provider spend. */
+    readonly costUsd: number;
+    /** Aggregate token usage, derived from `costTelemetry.providerUsage`. */
+    readonly usage: UsageSummary;
+    /** Terminal failure message (from the terminal `RUN_ERROR` event) when `!ok`. */
+    readonly error?: string;
+}
+/**
+ * The reason a schema-constrained decode did not yield a value:
+ *   - `schema_violation` — the model output failed schema validation.
+ *   - `uncertain` — the model signalled low confidence / declined to commit.
+ *   - `refused` — the model refused the request.
+ */
+export type RunRefusalReason = "schema_violation" | "uncertain" | "refused";
+/**
+ * The typed outcome of a `run<T>({ responseFormat })`: EITHER a schema-valid
+ * decoded value OR a typed refusal — there is no untyped path that silently
+ * yields a hallucinated object. `T` is the decoded value type.
+ */
+export type RunOutcome<T = unknown> = {
+    readonly kind: "decoded";
+    readonly value: T;
+} | {
+    readonly kind: "refused";
+    readonly reason: RunRefusalReason;
+    readonly detail?: string;
+};
+/** One item's settled result inside a {@link BatchResult}. */
+export interface BatchItemResult<T = unknown> extends SettledResult {
+    readonly runId: string;
+    /** Present only for a `responseFormat`-decoded item. */
+    readonly outcome?: RunOutcome<T>;
+}
+/**
+ * The result of `aex.batch(items, …)`: every item's settled result PLUS a real
+ * rollup. The rollup is honest because `run()` awaits settle, so every item's
+ * `costUsd`/`usage` is populated — a missing cost is a typed absent, not a
+ * silent `$0`.
+ */
+export interface BatchResult<T = unknown> {
+    readonly results: readonly BatchItemResult<T>[];
+    readonly totalCostUsd: number;
+    readonly totalUsage: UsageSummary;
+    readonly okCount: number;
+    readonly failed: readonly BatchItemResult<T>[];
+}
 /**
  * Filters for {@link import("./operations.js").listRuns} / the CLI's `aex runs`.
  * Every field is optional; omitting all of them lists the most recent runs in the
@@ -192,6 +278,37 @@ export interface RunListPage {
     readonly runs: readonly RunSummary[];
     readonly nextCursor?: string;
 }
+/**
+ * The minimal capability a value must carry to be RESOLVABLE through the run
+ * facade — `getRun` / `listRunEvents` / `listOutputs` all key on this `id`.
+ * Encodes the "handed ⇒ resolvable" invariant at the type level: anything the
+ * platform hands you as a run reference exposes a resolvable `id`, so a run can
+ * never be surfaced as a bare unresolvable string.
+ */
+export interface ResolvableRunRef {
+    readonly id: string;
+}
+/**
+ * A subagent CHILD run, enumerated under its parent via `GET /runs/:id/children`.
+ * A first-class, lineage-discoverable run reference: it {@link ResolvableRunRef}
+ * (its `id` resolves through the run facade — events/outputs/getRun), carries the
+ * lineage (`parentRunId`/`depth`) and the terminal outcome/cost, so a child is
+ * observable exactly like a top-level run.
+ */
+export interface ChildRunRef extends ResolvableRunRef {
+    /** The parent run this child was spawned by. */
+    readonly parentRunId: string;
+    /** The child's run status. */
+    readonly status: string;
+    /** Subagent nesting depth (1 = direct child of the top-level run). */
+    readonly depth?: number;
+    /** Settled AEX showback estimate (USD) for the child, when present. */
+    readonly costUsd?: number;
+    readonly createdAt?: string;
+    readonly terminalAt?: string | null;
+    /** The child's terminal outcome once settled. */
+    readonly lastTurnOutcome?: SessionTerminalOutcome;
+}
 /**
  * Cross-run output search query (`Aex.sessions.searchOutputs`). Restrict to a
  * corpus with `runIds`; filter by filename substring / extension / content type.
@@ -202,8 +319,13 @@ export interface RunListPage {
 export interface OutputSearchQuery {
     /** Restrict the search to these runs (the chat corpus allow-list). */
     readonly runIds?: readonly string[];
-    /** Case-insensitive substring match on the output filename. */
-    readonly filename?: string;
+    /**
+     * Filename match. A string is a case-insensitive SUBSTRING match; a RegExp is
+     * tested as given. Unified with {@link OutputQuery.filename} (`string | RegExp`)
+     * so the same value works on `find()` and `search()` — feed it through
+     * {@link import("./operations.js").toFilenameMatcher} rather than assuming a string.
+     */
+    readonly filename?: string | RegExp;
     /** File extension, with or without a leading dot. Case-insensitive. */
     readonly extension?: string;
     /** Exact content type or a prefix wildcard such as `image/*`. */
@@ -223,38 +345,6 @@ export interface OutputSearchHit {
 export interface OutputSearchPage {
     readonly hits: readonly OutputSearchHit[];
 }
-/**
- * A run event as recorded by the dashboard. Includes the `type` field
- * that the `is*Event` type guards narrow on plus any provider payload.
- *
- * The unified-stream discriminators (`channel`, `source`, `sourceSeq`,
- * `emittedAt`, `receivedAt`, `level`) carry through from the coordinator
- * envelope (see `event-envelope.ts` —
- * {@link import("./event-envelope.js").AexEvent}) so SDK/CLI consumers can
- * split/filter the one stream by channel or source. All are OPTIONAL: archived
- * events from before the unification (and any producer that omits an ordering
- * attribute) lack them, an absent `channel` means `"event"` (see `channelOf`),
- * and `level` is present only on `log`-channel records.
- */
-export interface RunEvent {
-    readonly id: string;
-    readonly type: string;
-    readonly runId?: string;
-    readonly recordedAt?: string;
-    /** Which sub-stream this record rides — `"event"` (typed) or `"log"`. Absent ⇒ `"event"`. */
-    readonly channel?: import("./event-envelope.js").AexEventChannel;
-    /** Coarse origin classifier. See {@link AexEventSource}. */
-    readonly source?: import("./event-envelope.js").AexEventSource;
-    /** Per-source monotonic counter assigned at the source (carried, not re-ordered). */
-    readonly sourceSeq?: number;
-    /** Source wall-clock ms at emit (carried for a best-effort client time view). */
-    readonly emittedAt?: number;
-    /** The DO's authoritative receive-time (wall-clock ms) stamped at ingest, companion to `seq`. */
-    readonly receivedAt?: number;
-    /** Log severity, first-class on a `channel: "log"` record ("info" | "warn" | "error"). */
-    readonly level?: import("./event-envelope.js").AexLogLevel;
-    readonly [key: string]: unknown;
-}
 /** Status of a per-run webhook delivery. Terminal: delivered/exhausted/invalid. */
 export type RunWebhookDeliveryStatus = "pending" | "delivering" | "retrying" | "delivered" | "exhausted" | "invalid";
 /**

package/dist/_contracts/runtime-types.js

@@ -1,2 +1,34 @@
-export {};
+/**
+ * Project a {@link UsageSummary} from the settle-written
+ * {@link RunCostProviderUsage} entries — the SINGLE server source of token
+ * usage ({@link Run.costTelemetry}`.providerUsage`). Sums each field across all
+ * provider entries; a field is present only when at least one entry carried it.
+ * This retires the dead `session.usage` / `aex.usage`-event usage path: the SDK
+ * derives usage from cost telemetry, never re-reads a dual-written top-level
+ * `usage`. Pure.
+ */
+export function usageFromProviderUsage(providerUsage) {
+    if (!providerUsage || providerUsage.length === 0)
+        return {};
+    let inputTokens;
+    let outputTokens;
+    let cacheReadInputTokens;
+    let cacheCreationInputTokens;
+    let totalTokens;
+    const add = (acc, value) => value === undefined ? acc : (acc ?? 0) + value;
+    for (const entry of providerUsage) {
+        inputTokens = add(inputTokens, entry.inputTokens);
+        outputTokens = add(outputTokens, entry.outputTokens);
+        cacheReadInputTokens = add(cacheReadInputTokens, entry.cacheReadInputTokens);
+        cacheCreationInputTokens = add(cacheCreationInputTokens, entry.cacheCreationInputTokens);
+        totalTokens = add(totalTokens, entry.totalTokens);
+    }
+    return {
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+        ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+        ...(totalTokens !== undefined ? { totalTokens } : {})
+    };
+}
 //# sourceMappingURL=runtime-types.js.map