@aexhq/sdk 0.40.16 → 0.41.0

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-6a03ce618806a3cbd18663d4a1187106b1c6fecd4256e5f78d043b7480967505  cli.mjs
+b55fdfa4ea2269e666c3232ae406e9f691422193792a6258af7373ce2756d31e  cli.mjs

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-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 { HttpClient, SecretString, type AexEventView, type AgentsMdRecord, type ApprovalGate, type BatchResult, type BillingCheckoutRequest, type BillingHostedSession, type BillingLedgerPage, type BillingLedgerQuery, type BillingPortalRequest, type BillingSummary, type ChildSessionRef, type DebugSink, type FetchLike, type FileRecord, type SessionFile, type SessionFileType, type SessionFileLink, type SessionFileLinkOptions, type SessionFileQuery, type SessionFileText, type OutputMode, type ReadSessionFileTextOptions, type ResponseFormat, type SessionFileSearchQuery, type SessionFileSearchPage, type TurnOutcome, type Session, type SessionCreateRequest, type SessionListPage, type SessionListQuery, type SessionMessage, type SessionStateChangeAccepted, type SessionTerminalOutcome, type SessionTurn, type SettledResult, type PlatformEnvironmentInput, type PlatformSubmission, type SessionRecord, type ModelName, type TurnTrace, type SessionWebhookDelivery, type ProviderName, type SecretRecord, type SessionUnit, 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, type ZipStreamDriver } from "./file.js";
@@ -28,7 +28,7 @@ export interface AexOptions {
      * Built-in transport retry policy. Every BFF request is retried on transient
      * failures (HTTP 429/500/502/503/504/529 and network errors) with bounded
      * exponential backoff + jitter, honoring `Retry-After`. Billable submits carry
-     * a stable idempotency key, so a retry never creates a duplicate billable run.
+     * a stable idempotency key, so a retry never creates a duplicate billable session turn.
      *
      * Omit for sensible defaults (4 attempts, ~2 min budget); pass an object to
      * tune `maxAttempts` / delays / `maxElapsedMs`; pass `false` to disable.
@@ -36,26 +36,24 @@ export interface AexOptions {
     readonly retry?: RetryOptions | false;
 }
 /**
- * The unified SETTLED result of {@link Aex.run}. Extends the contracts
- * {@link SettledResult} (the ONE settled shape `run()` and `done()` share), so
+ * The unified SETTLED result of {@link Aex.start}. Extends the contracts
+ * {@link SettledResult} (the ONE settled shape `start()` 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.
+ * (`number`, `>= 0`), and `usage` are ALWAYS present — `start()` awaits the settle
+ * commit by default. Adds the one-shot conveniences: the session-record-compatible record,
+ * events, decoded trace, assistant text, and captured files.
  *
- * `T` is the `responseFormat` decode type: when the run was submitted with a
+ * `T` is the `responseFormat` decode type: when the session was submitted with a
  * `json_schema` `responseFormat`, {@link outcome} carries the typed decoded
  * value or a typed refusal.
  */
-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;
+export interface SessionResult<T = unknown> extends SettledResult {
+    readonly sessionId: string;
+    /** Session-record view of the underlying session. */
+    readonly record: SessionRecord;
     /** The underlying resumable session record (its lifecycle `status` is idle/suspended when resumable). */
     readonly session?: Session;
-    /** The turn accepted for this one-shot run. */
+    /** The turn accepted for this one-shot session. */
     readonly turn?: SessionTurn;
     /** The assistant's final text. */
     readonly text: string;
@@ -64,27 +62,27 @@ export interface RunResult<T = unknown> extends SettledResult {
     /** 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[];
+    readonly trace: TurnTrace;
+    /** The session's captured files. */
+    readonly files: readonly SessionFile[];
     /**
-     * The typed schema-decode outcome — present only when the run was submitted
+     * The typed schema-decode outcome — present only when the session 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 outcome?: RunOutcome<T>;
+    readonly outcome?: TurnOutcome<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 {
+/** Options for {@link Aex.start}. */
+export interface StartSessionOptions {
     /** Overall wait budget (ms) for the one-shot session turn to park. */
     readonly timeoutMs?: number;
     readonly webSocketFactory?: WebSocketFactory;
     readonly idleTimeoutMs?: number;
     readonly pingIntervalMs?: number;
-    /** Throw a {@link RunStateError} when the run does not succeed. Default false. */
+    /** Throw a {@link SessionStateError} when the session does not succeed. Default false. */
     readonly throwOnFailure?: boolean;
     /**
      * When the result resolves. `'settle'` (DEFAULT) waits (bounded) for the
@@ -95,9 +93,9 @@ export interface RunCollectOptions {
      */
     readonly await?: SettleAwait;
 }
-/** The result of {@link Aex.submit}: the run id + a resumable session handle. */
+/** The result of {@link Aex.submit}: the session id + a resumable session handle. */
 export interface SubmitResult {
-    readonly runId: string;
+    readonly sessionId: string;
     readonly session: SessionHandle;
 }
 /** Options for {@link Aex.batch}. */
@@ -117,7 +115,7 @@ export interface SessionOverrides {
     readonly timeout?: string;
     readonly maxSpendUsd?: number;
     /**
-     * Per-run iteration cap (agent loop turns). Defaults + ceiling are enforced
+     * Per-session iteration cap (agent loop turns). Defaults + ceiling are enforced
      * server-side; omit to accept the platform default. A positive integer.
      */
     readonly maxTurns?: number;
@@ -148,12 +146,12 @@ export interface SessionCreateOptions {
      * {@link Providers} symbol const, e.g. `provider: Providers.DEEPSEEK`. When
      * omitted it is derived from `model`; if supplied it MUST serve the model.
      */
-    readonly provider?: RunProvider;
+    readonly provider?: ProviderName;
     /**
      * Closed public model id. Prefer the {@link Models} symbol const, e.g.
      * `Models.CLAUDE_HAIKU_4_5`.
      */
-    readonly model: RunModel;
+    readonly model: ModelName;
     readonly system?: string;
     /**
      * Tools available to the agent. Each entry is a custom {@link Tool} bundle or
@@ -171,11 +169,11 @@ export interface SessionCreateOptions {
     readonly files?: readonly File[];
     readonly mcpServers?: readonly McpServer[];
     /**
-     * Output capture policy for the session's output files. `allowedDirs` omitted
-     * captures every regular file the session creates or modifies; the listed
-     * roots narrow capture; `deniedDirs` subtracts noise.
+     * File capture policy for the session's captured files. Omit `allowedDirs`
+     * to expose regular workspace files from the latest complete checkpoint;
+     * listed roots narrow capture, and `deniedDirs` subtracts noise.
      */
-    readonly outputs?: {
+    readonly fileCapture?: {
         readonly allowedDirs?: readonly string[];
         readonly deniedDirs?: readonly string[];
         readonly captureTimeoutMs?: number;
@@ -205,7 +203,7 @@ export interface SessionCreateOptions {
      * 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
+     * `start<T>()`'s `result.outcome` (`{ kind:'decoded', value }` or
      * `{ kind:'refused', reason }`) — never an untyped hallucinated object.
      */
     readonly responseFormat?: ResponseFormat;
@@ -219,7 +217,7 @@ export interface SessionCreateOptions {
     readonly metadata?: PlatformSubmission["metadata"];
     readonly idempotencyKey?: string;
     /** BYOK provider key(s), keyed by provider. */
-    readonly apiKeys?: Partial<Record<RunProvider, string>>;
+    readonly apiKeys?: Partial<Record<ProviderName, string>>;
     readonly environment?: SessionEnvironmentOptions;
     /**
      * Managed runtime size. One of the closed {@link RuntimeSize} preset tokens.
@@ -250,7 +248,7 @@ export interface SessionSendOptions {
      */
     readonly await?: SettleAwait;
 }
-export interface SessionRunOptions extends SessionCreateOptions {
+export interface SessionStartOptions extends SessionCreateOptions {
     readonly message: SessionInput;
     readonly deleteAfter?: boolean;
     readonly messageIdempotencyKey?: string;
@@ -259,7 +257,7 @@ export interface SessionRunOptions extends SessionCreateOptions {
 /**
  * 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`,
+ * `start()`: 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 {
@@ -268,16 +266,16 @@ export interface SessionTurnResult<T = unknown> extends SettledResult {
     readonly turn: SessionTurn;
     readonly text: string;
     readonly events: readonly AexEventView[];
-    readonly outputs: readonly Output[];
+    readonly files: readonly SessionFile[];
     readonly messages: readonly Message[];
     /** The typed schema-decode outcome when a `json_schema` `responseFormat` was set. */
-    readonly outcome?: RunOutcome<T>;
+    readonly outcome?: TurnOutcome<T>;
 }
-export interface SessionRunResult extends SessionTurnResult {
+export interface SessionStartResult extends SessionTurnResult {
 }
 export declare class SessionTurnStream implements AsyncIterable<AexEventView> {
     #private;
-    constructor(run: () => AsyncGenerator<AexEventView, SessionTurnResult, void>);
+    constructor(stream: () => AsyncGenerator<AexEventView, SessionTurnResult, void>);
     [Symbol.asyncIterator](): AsyncIterator<AexEventView>;
     done(): Promise<SessionTurnResult>;
 }
@@ -307,40 +305,40 @@ export interface SessionEvents {
     first(): Promise<AexEventView | undefined>;
     stream(options?: StreamEventsOptions): AsyncIterable<AexEventView>;
     streamEnvelopes(options?: StreamEnvelopesOptions): AsyncIterable<AexEventView>;
-    archiveLink(options?: OutputLinkOptions): Promise<OutputLink>;
+    archiveLink(options?: SessionFileLinkOptions): Promise<SessionFileLink>;
     /** Download the events-namespace archive as a zip. */
-    download(options?: OutputDownloadOptions): Promise<Uint8Array>;
+    download(options?: DownloadOptions): Promise<Uint8Array>;
 }
 /**
- * Accessor over the session's captured output files (`session.outputs()`):
+ * Accessor over the session's captured files (`session.files()`):
  * enumerate, read one as capped text, locate/resolve, and download.
  */
-export interface SessionOutputs {
-    list(query?: OutputQuery): Promise<readonly Output[]>;
-    last(): Promise<Output | undefined>;
-    first(): Promise<Output | undefined>;
-    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`) /
+export interface SessionFiles {
+    list(query?: SessionFileQuery): Promise<readonly SessionFile[]>;
+    last(): Promise<SessionFile | undefined>;
+    first(): Promise<SessionFile | undefined>;
+    read(selector: SessionFileSelector, options?: ReadSessionFileTextOptions): Promise<SessionFileText>;
+    find(query: SessionFileQuery): Promise<readonly SessionFile[]>;
+    findOne(query: SessionFileQuery): Promise<SessionFile | null>;
+    /**
+     * Search THIS session's captured files 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>;
+    search(query?: PerSessionFileSearchQuery): Promise<SessionFileSearchPage>;
+    link(selectorOrQuery: SessionFileLinkSelector, options?: SessionFileLinkOptions): Promise<SessionFileLink>;
+    fetch(selectorOrQuery: SessionFileLinkSelector, options?: SessionFileLinkOptions): Promise<Response>;
+    /** No selector = files-namespace zip; with selector = one file's raw bytes. */
+    download(selector?: SessionFileSelector, options?: DownloadOptions): Promise<Uint8Array>;
 }
-/** A per-session output search — {@link OutputSearchQuery} without the cross-run `runIds` corpus. */
-export type PerSessionOutputSearchQuery = Omit<OutputSearchQuery, "runIds">;
+/** A per-session file search — {@link SessionFileSearchQuery} without the cross-session `sessionIds` corpus. */
+export type PerSessionFileSearchQuery = Omit<SessionFileSearchQuery, "sessionIds">;
 /**
  * Accessor over the session's webhook delivery ledger (`session.webhooks()`).
  */
 export interface SessionWebhooks {
-    list(): Promise<readonly RunWebhookDelivery[]>;
+    list(): Promise<readonly SessionWebhookDelivery[]>;
     redeliver(deliveryId: string): Promise<void>;
 }
 export declare class SessionHandle {
@@ -373,12 +371,12 @@ export declare class SessionHandle {
     /** 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) —
+     * Enumerate this session's subagent CHILD sessions (`GET /sessions/:id/children`). Each is
+     * a {@link ChildSessionHandle} backed by the RUN facade (getSessionRecord/events/files) —
      * NOT `openSession` — so every child the platform hands you is resolvable, with
-     * its lineage (`parentRunId`/`depth`) and terminal outcome exposed.
+     * its lineage (`parentSessionId`/`depth`) and terminal outcome exposed.
      */
-    children(): Promise<readonly ChildRunHandle[]>;
+    children(): Promise<readonly ChildSessionHandle[]>;
     /**
      * Accessor for the session's assistant messages. `all()` returns them
      * oldest-first; `last()`/`first()` return a single entry or `undefined` when
@@ -394,12 +392,12 @@ export declare class SessionHandle {
      */
     events(): SessionEvents;
     /**
-     * Accessor for the session's captured output files: `list`/`last`/`first`
+     * Accessor for the session's captured files: `list`/`last`/`first`
      * enumerate them; `read` streams one as capped text; `find`/`findOne`/`link`/
-     * `fetch` locate and resolve them; `download` fetches the outputs-namespace
+     * `fetch` locate and resolve them; `download` fetches the files-namespace
      * zip (no selector) or one file's raw bytes (with selector).
      */
-    outputs(): SessionOutputs;
+    files(): SessionFiles;
     /**
      * Accessor for the session's webhook delivery ledger: `list()` returns the
      * delivery attempts; `redeliver(id)` re-sends the frozen payload under the
@@ -410,31 +408,31 @@ export declare class SessionHandle {
     refresh(): Promise<Session>;
     /**
      * Poll the session record until it reaches a parked/terminal status (idle,
-     * suspended, error, or any terminal run status). Throws if `timeoutMs`
+     * suspended, error, or any terminal session status). Throws if `timeoutMs`
      * elapses first. Updates the stored record.
      */
-    wait(options?: WaitForRunOptions): Promise<Session>;
+    wait(options?: WaitForSessionOptions): Promise<Session>;
     /**
-     * Fetch the self-contained `RunUnit` for this session: parsed submission,
-     * attempts, indexed events, outputs, capture failures, proxy-call audit, and
+     * Fetch the self-contained `SessionUnit` for this session: parsed submission,
+     * attempts, indexed events, session files, capture failures, proxy-call audit, and
      * resolved skills. Use this when you need fields beyond the session record.
      *
      * On the managed plane this is a LEAN summary — the aggregate collections
-     * (`attempts` / `events.entries` / `outputs` / `rawEventPages`) default to
-     * empty. For authoritative per-run data use `outputs()` / `events()` /
+     * (`attempts` / `events.entries` / `sessionFiles` / `rawEventPages`) default to
+     * empty. For authoritative per-session data use `files()` / `events()` /
      * `messages()`. The returned shape is always type-valid (never `undefined`
      * where the type promises an array/page), so array/page access is safe.
      */
-    unit(): Promise<RunUnit>;
+    unit(): Promise<SessionUnit>;
     /**
      * Download EVERYTHING public about this session as one zip, assembled
      * client-side from the public read endpoints. Organised into `metadata/`,
-     * `events/`, and `outputs/` folders, plus a `manifest.json`. Pass `to` to
+     * `events/`, and `files/` folders, plus a `manifest.json`. Pass `to` to
      * also write the bytes to a file path while still returning them.
      */
-    download(options?: OutputDownloadOptions): Promise<Uint8Array>;
+    download(options?: DownloadOptions): Promise<Uint8Array>;
     /** Download only the session record (the `metadata` namespace) as a zip. */
-    downloadMetadata(options?: OutputDownloadOptions): Promise<Uint8Array>;
+    downloadMetadata(options?: DownloadOptions): Promise<Uint8Array>;
 }
 export declare class SessionClient {
     #private;
@@ -445,66 +443,54 @@ export declare class SessionClient {
     delete(sessionId: string, options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<void>;
     list(query?: SessionListQuery): Promise<SessionListPage>;
     /**
-     * Accessor over one session's captured output files, addressed by id without
-     * opening a handle. Returns the SAME rich {@link SessionOutputs} surface as
-     * `session.outputs()` — `aex.sessions.outputs(id).list()` /
+     * Accessor over one session's captured files, addressed by id without
+     * opening a handle. Returns the SAME rich {@link SessionFiles} surface as
+     * `session.files()` — `aex.sessions.files(id).list()` /
      * `.read(selector)` / `.download()` / … — so the workspace client and the
      * live handle share one accessor convention.
      */
-    outputs(sessionId: string): SessionOutputs;
-    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>;
+    files(sessionId: string): SessionFiles;
+    start(options: SessionStartOptions): Promise<SessionStartResult>;
 }
-/** A run-facade events accessor (list + polling stream) keyed on a run id. */
-export interface RunEvents {
+/** Child-session events accessor (list + polling stream) keyed on a session id. */
+export interface ChildSessionEvents {
     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 session facade files accessor (a subset of {@link SessionFiles}) keyed on a session id. */
+export interface SessionFiles {
+    list(query?: SessionFileQuery): Promise<readonly SessionFile[]>;
+    find(query: SessionFileQuery): Promise<readonly SessionFile[]>;
+    findOne(query: SessionFileQuery): Promise<SessionFile | null>;
+    read(selector: SessionFileSelector, options?: ReadSessionFileTextOptions): Promise<SessionFileText>;
+    link(selectorOrQuery: SessionFileLinkSelector, options?: SessionFileLinkOptions): Promise<SessionFileLink>;
+    download(selector?: SessionFileSelector, options?: DownloadOptions): 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
+ * A first-class, lineage-discoverable SUBAGENT child session — handed out by
+ * `session.children()`, backed by the session-record facade
+ * (getSessionRecord/events/files), NOT `openSession`. Every child the platform hands you
+ * is resolvable through this handle; its lineage (`parentSessionId`/`depth`) and
  * terminal outcome (`status`) are first-class.
  */
-export declare class ChildRunHandle {
+export declare class ChildSessionHandle {
     #private;
-    constructor(http: HttpClient, ref: ChildRunRef, fetch?: FetchLike);
+    constructor(http: HttpClient, ref: ChildSessionRef, fetch?: FetchLike);
     get id(): string;
-    get parentRunId(): string;
+    get parentSessionId(): string;
     get depth(): number | undefined;
-    /** The child's run status (a real run terminal outcome once settled). */
+    /** The child's session status (a real session 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;
+    get ref(): ChildSessionRef;
+    /** Re-read the child session record (status, lineage, costTelemetry). */
+    get(): Promise<SessionRecord>;
+    /** The child's events over the session-record facade (`/sessions/:id/events`). */
+    events(): ChildSessionEvents;
+    /** The child's captured files over the session-record facade (`/sessions/:id/files`). */
+    files(): SessionFiles;
     /** This child's own subagent children (recursive lineage). */
-    children(): Promise<readonly ChildRunHandle[]>;
-    /** Cancel the child run (run facade `POST /runs/:id/cancel`). */
+    children(): Promise<readonly ChildSessionHandle[]>;
+    /** Cancel the child session (session record facade `POST /sessions/:id/cancel`). */
     cancel(): Promise<void>;
 }
 /**
@@ -547,40 +533,40 @@ export interface StreamEnvelopesOptions {
     readonly terminalDrainGraceMs?: number;
     /**
      * End the stream settle-consistently. By default the iterator ends on the
-     * AG-UI terminal event (RUN_FINISHED / RUN_ERROR) or the managed-session
+     * AG-UI terminal event (TURN_FINISHED / TURN_ERROR) or the managed-session
      * terminal park (`aex.session.succeeded` / failed / timed_out / cancelled /
      * idle / suspended). These are render-complete UX signals, emitted before the
-     * platform commit is necessarily read-consistent, so a `getRun` immediately
+     * platform commit is necessarily read-consistent, so a `getSessionRecord` immediately
      * after can still read `running`. With `settleConsistent: true` the iterator
      * keeps reading PAST the render terminal until the post-mirror
-     * `aex.run.settled` barrier when the plane emits it, or a session park
-     * fallback otherwise. When it ends a subsequent `getRun` is guaranteed
-     * terminal and `listOutputs` is complete.
-     * Note: outputs are durable at the RUN_FINISHED event already; this only adds
-     * the run-RECORD consistency barrier.
+     * `aex.session.settled` barrier when the plane emits it, or a session park
+     * fallback otherwise. When it ends a subsequent `getSessionRecord` is guaranteed
+     * terminal and `listSessionFiles` is complete.
+     * Note: files are durable at the TURN_FINISHED event already; this only adds
+     * the session-record consistency barrier.
      */
     readonly settleConsistent?: boolean;
 }
-export interface WaitForRunOptions {
+export interface WaitForSessionOptions {
     readonly intervalMs?: number;
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
-export type OutputFilePathMatch = "exact" | "suffix";
-export interface OutputFilePathSelector {
+export type SessionFilePathMatch = "exact" | "suffix";
+export interface SessionFilePathSelector {
     readonly path: string;
-    readonly match?: OutputFilePathMatch;
+    readonly match?: SessionFilePathMatch;
 }
-export interface OutputFileIdSelector {
+export interface SessionFileIdSelector {
     readonly id: string;
 }
-export type OutputFileSelector = Output | OutputFileIdSelector | OutputFilePathSelector;
-export type OutputLinkSelector = string | OutputFileSelector | OutputQuery;
-export interface OutputDownloadOptions {
+export type SessionFileSelector = SessionFile | SessionFileIdSelector | SessionFilePathSelector;
+export type SessionFileLinkSelector = string | SessionFileSelector | SessionFileQuery;
+export interface DownloadOptions {
     readonly to?: string;
     /**
-     * Per-attempt timeout for fetching and reading the selected output body.
-     * Defaults to 30_000ms; idempotent output downloads retry once on timeout.
+     * Per-attempt timeout for fetching and reading the selected file body.
+     * Defaults to 30_000ms; idempotent file downloads retry once on timeout.
      */
     readonly timeoutMs?: number;
 }
@@ -613,6 +599,8 @@ export declare class FilesClient {
     list(): Promise<readonly FileRecord[]>;
     get(fileId: string): Promise<FileRecord>;
     delete(fileId: string): Promise<void>;
+    /** Cross-session captured-file metadata search. */
+    search(query?: SessionFileSearchQuery): Promise<SessionFileSearchPage>;
 }
 /**
  * Workspace skill registry operations exposed under `client.skills`.
@@ -632,7 +620,7 @@ export declare class SkillsClient {
  * Workspace secret management exposed under `client.secrets`, mirroring
  * `client.agentsMd` / `client.files`.
  *
- * Lifecycle parity with assets: a `Secret.value(...)` is per-run and
+ * Lifecycle parity with assets: a `Secret.value(...)` is per-session and
  * gone at terminal; `set` (or promoting an ephemeral via `secret.upload`)
  * persists a named, searchable workspace secret you can `get` (metadata),
  * `rotate`, `list`, and `delete`. The identity is the `name`; the value rotates
@@ -675,7 +663,7 @@ export declare class SecretsClient {
  * Unified user-facing client for the aex platform. The same class
  * powers the published `@aexhq/sdk` SDK and (under the hood) every host-side
  * subcommand of the in-container `aex` CLI. All operations talk to
- * the dashboard BFF and operate on durable run records.
+ * the dashboard BFF and operate on durable session records.
  *
  * The SDK never asks the caller for a workspace id — workspace identity
  * is derived server-side from the API key on every request. Use
@@ -689,8 +677,6 @@ 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);
     /**
@@ -732,7 +718,7 @@ export declare class Aex {
     /**
      * Internal: upsert already-uploaded skill metadata into the workspace registry.
      * The bytes are staged through `_uploadAsset`; this call binds the content hash
-     * to a mutable workspace skill name before the run references that name.
+     * to a mutable workspace skill name before the session references that name.
      */
     _upsertSkill(args: {
         readonly name: string;
@@ -746,31 +732,31 @@ export declare class Aex {
      * Convenience one-shot on top of the canonical session API:
      * open a session, send `message` as the first turn, stream until the session
      * parks (`idle` / `suspended` / `error`), then return the collected text,
-     * events, outputs, and session record. The returned `runId` is the session id,
-     * so callers can resume later with `openSession(runId)`.
+     * events, files, and session record. The returned `sessionId` is the session id,
+     * so callers can resume later with `openSession(sessionId)`.
      */
-    run<T = unknown>(options: SessionRunOptions, opts?: RunCollectOptions): Promise<RunResult<T>>;
+    start<T = unknown>(options: SessionStartOptions, opts?: StartSessionOptions): Promise<SessionResult<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)`.
+     * settle (the honest counterpart to await-settle `start()`). Resolves with the
+     * `sessionId` + a resumable {@link SessionHandle} immediately; observe the session via
+     * a `webhook`, the event stream, or `openSession(sessionId)`.
      */
-    submit(options: SessionRunOptions): Promise<SubmitResult>;
+    submit(options: SessionStartOptions): Promise<SubmitResult>;
     /**
-     * Run a batch of one-shot items with a bounded worker pool, returning every
+     * SessionRecord 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
+     * because each `start()` 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>>;
+    batch<T = unknown>(items: readonly SessionStartOptions[], options?: BatchOptions): Promise<BatchResult<T>>;
     openSession(options: SessionCreateOptions): Promise<SessionHandle>;
     openSession(sessionId: string): Promise<SessionHandle>;
     /**
      * Delete a workspace asset blob from the shared content-addressed store
      * (`assets/<workspaceId>/<hash>`). Accepts `sha256:<hex>` or a bare
-     * 64-hex digest. Runs that already snapshotted the asset are unaffected.
+     * 64-hex digest. Sessions that already snapshotted the asset are unaffected.
      */
     deleteWorkspaceAsset(hash: string): Promise<void>;
     whoami(): Promise<WhoAmI>;
@@ -816,4 +802,4 @@ export declare class Aex {
  * public SDK surface (index.ts controls that).
  */
 export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
-export type { OutputFileType, OutputLink, OutputLinkOptions, OutputQuery };
+export type { SessionFileType, SessionFileLink, SessionFileLinkOptions, SessionFileQuery };