@aexhq/sdk 0.33.1 → 0.35.0

package/dist/client.d.ts

@@ -1,11 +1,12 @@
-import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputFileType, type OutputLink, type OutputLinkOptions, type OutputQuery, type OutputText, type OutputMode, type ReadOutputTextOptions, type RunListPage, type RunListQuery, type OutputSearchQuery, type OutputSearchPage, type Session, type SessionCreateRequest, type SessionEvent, type SessionListPage, type SessionListQuery, type SessionStateChangeAccepted, type SessionTurn, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type Run, type RunModel, type RunEvent, type RunTrace, type UsageSummary, type RunLimits, type RunWebhookDelivery, type RunProvider, type SecretRecord, type SecretReveal, type RunUnit, type BuiltinToolName, type RuntimeSize, type Skill as SkillRecord, type WebSocketFactory, type WhoAmI } from "./_contracts/index.js";
+import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type AssistantTextEntry, 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 SessionStateChangeAccepted, type SessionTurn, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type Run, type RunModel, type RunEvent, type RunTrace, type UsageSummary, type RunWebhookDelivery, type RunProvider, type SecretRecord, type RunUnit, type BuiltinToolName, type RuntimeSize, 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 { McpServer } from "./mcp-server.js";
 import { ProxyEndpoint } from "./proxy-endpoint.js";
+import { type RetryOptions } from "./retry.js";
 import { Secret } from "./secret.js";
-import { Skill } from "./skill.js";
+import { SkillTool } from "./skill-tool.js";
 import { Tool } from "./tool.js";
 export interface AgentExecutorOptions {
     /** Workspace-scoped SDK API token. */
@@ -24,165 +25,19 @@ export interface AgentExecutorOptions {
      * route the traces elsewhere. Purely local — nothing is uploaded.
      */
     readonly debug?: boolean | DebugSink;
-}
-/**
- * Per-run submission options. Everything the user wants to send is
- * spelled out at the call site:
- *
- *   - `model` / `system` / `prompt` — the agent's brief.
- *   - `skills` — array of local `Skill` instances
- *     (`Skill.fromFiles` / `Skill.fromPath`). Local skills are materialized
- *     to the hosted asset store before the run lands.
- *   - `mcpServers` — array of `McpServer` instances (headers split into
- *     `secrets.mcpServers` server-side; the public submission only
- *     carries `{ name, url }`).
- *   - `proxyEndpoints` — array of `ProxyEndpoint` instances. The auth
- *     secret is bundled into the constructor and split into
- *     `secrets.proxyEndpointAuth` server-side; the public submission
- *     only carries the declaration (`{ name, baseUrl, authShape, … }`).
- *   - `secrets.apiKeys` — the BYOK provider key(s), keyed by provider. A key
- *     for the selected provider is REQUIRED unless this is an admitted child
- *     run inheriting keys from its parent. The platform never holds a
- *     long-lived provider key on your behalf.
- *
- * `idempotencyKey` is auto-generated when omitted; pass one explicitly
- * if you want client-driven retry safety across process restarts.
- */
-export interface SubmitOptions {
-    /**
-     * Upstream provider selector. Prefer naming it explicitly with the
-     * {@link Providers} symbol const, e.g. `provider: Providers.DEEPSEEK`. The
-     * same model id can route through different providers, so `provider` is a
-     * first-class field — pass it alongside `model` rather than letting the model
-     * alone decide routing. The BYOK key for the selected provider is supplied as
-     * `secrets.apiKeys[provider]`.
-     *
-     * Optional today: when omitted it is derived from `model` (each currently
-     * supported model maps to a single provider), so existing call sites keep
-     * working. If supplied it MUST match the model's provider or `submit`
-     * throws.
-     */
-    readonly provider?: RunProvider;
-    /**
-     * Closed public model id. Prefer the {@link Models} symbol const, e.g.
-     * `Models.CLAUDE_HAIKU_4_5`. Pair it with an explicit {@link Providers} value
-     * on `provider`; if `provider` is omitted it is derived from this model.
-     */
-    readonly model: RunModel;
-    readonly system?: string;
-    readonly prompt: string | readonly string[];
-    readonly skills?: readonly Skill[];
     /**
-     * Tools available to the agent. Each entry is either a custom {@link Tool}
-     * bundle, or a BUILTIN tool reference — a bare name string, preferably
-     * `BuiltinTools.<name>` (e.g. `BuiltinTools.notebook_edit`) so a typo is a
-     * compile error. Builtin references compose with {@link includeBuiltinTools}:
-     * use them to cherry-pick a tool the default set omits (notebook editing), or
-     * to pick a narrow subset alongside `includeBuiltinTools: false`.
+     * 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.
      *
-     * Order in the agent's tool list: resolved builtin tools, then custom tools,
-     * then MCP tools.
-     */
-    readonly tools?: readonly (Tool | BuiltinToolName)[];
-    readonly agentsMd?: readonly AgentsMd[];
-    readonly files?: readonly File[];
-    readonly mcpServers?: readonly McpServer[];
-    /**
-     * Env-var secrets, keyed by env name. Each value is a {@link Secret}:
-     * `Secret.value(v)` (ephemeral per-run — vaulted at submit, deleted at the
-     * run's terminal) or `Secret.ref(handle)` (a persisted workspace secret,
-     * resolved server-side). The SDK splits these into value-free declarations on
-     * the hashed submission and ephemeral values into the vaulted secrets channel,
-     * so a value never enters the run snapshot or the idempotency hash. The
-     * runtime injects each as the named env var.
-     */
-    readonly secretEnv?: Readonly<Record<string, Secret>>;
-    readonly environment?: PlatformEnvironmentInput;
-    readonly metadata?: PlatformSubmission["metadata"];
-    /**
-     * Managed runtime size. One of the closed {@link RuntimeSize} preset tokens.
-     * Prefer the {@link RuntimeSizes} symbol const, e.g.
-     * `RuntimeSizes.SHARED_2X_8GB`.
-     */
-    readonly runtimeSize?: RuntimeSize;
-    /**
-     * Run deadline as a duration string (`"1h"`, `"90m"`, `"30s"`). Bounded to
-     * [1m, 6h]; omit for the 1h default. Applies to both runtimes.
-     */
-    readonly timeout?: string;
-    readonly proxyEndpoints?: readonly ProxyEndpoint[];
-    /**
-     * Output capture policy for the run's output files.
-     *
-     * - `allowedDirs` omitted: every regular file the session creates or
-     *   modifies is captured.
-     * - `allowedDirs` present: the listed roots narrow capture to those paths.
-     * - `deniedDirs` subtracts noise from the allowed roots.
-     *
-     * Captured bytes land in private storage and can be retrieved via
-     * `client.outputs(runId)` / `client.download(runId)`. See
-     * `packages/sdk/docs/outputs.md` for the full contract.
-     */
-    readonly outputs?: {
-        readonly allowedDirs?: readonly string[];
-        readonly deniedDirs?: readonly string[];
-        readonly captureTimeoutMs?: number;
-        readonly maxFileBytes?: number;
-        readonly maxTotalBytes?: number;
-        readonly maxFiles?: number;
-    };
-    /**
-     * Whether to inject the standard builtin tool set
-     * ({@link DEFAULT_BUILTIN_TOOLS} — every builtin except `notebook_edit`).
-     *
-     * - Omitted / `true` (default): inject the standard builtins.
-     * - `false`: inject NO builtins — useful for a pure-MCP / pure-custom run.
-     *   Cherry-pick a narrow subset back by listing builtin names in `tools`.
-     */
-    readonly includeBuiltinTools?: boolean;
-    /**
-     * Assistant-output granularity. `"buffered"` (default) delivers one event per
-     * assistant message; `"stream"` delivers per-token text deltas for live
-     * typing UIs.
-     */
-    readonly outputMode?: OutputMode;
-    /**
-     * Advanced inline secrets bundle (per-provider `apiKeys`, MCP headers, proxy
-     * auth, env secrets). Provider keys must use `secrets.apiKeys`.
-     */
-    readonly secrets?: PlatformInlineSecrets;
-    readonly idempotencyKey?: string;
-    /**
-     * Lineage parent (agent-session §9). When set, the server admits this run as
-     * a CHILD of `parentRunId` (same workspace required), enforcing the
-     * max-subagent-depth + per-root concurrency caps and persisting the lineage.
-     * The depth is always derived server-side from the parent row — clients name
-     * the parent, never the depth.
-     */
-    readonly parentRunId?: string;
-    /**
-     * Optional per-run callback URL. The platform delivers exactly the terminal
-     * `run.finished` event to `webhook.url` at the settle-consistent barrier,
-     * signed Standard-Webhooks style (verify with {@link verifyAexWebhook}). The
-     * URL must be https. It rides alongside `idempotencyKey` and never enters the
-     * idempotency hash, so re-submitting the same key with a different callback
-     * URL does not 409 (the URL is bound at first accept only).
-     */
-    readonly webhook?: {
-        readonly url: string;
-    };
-    /**
-     * Optional per-run override of the lineage limits — the max number of
-     * concurrent child runs and the max subagent depth. A sibling of
-     * {@link parentRunId}: these are dials the client *requests*; the server
-     * resolves each against the per-workspace ceiling and the hard platform
-     * ceiling, and an absent field falls back to the platform default. Only
-     * shape + positivity are validated client-side.
+     * Omit for sensible defaults (4 attempts, ~2 min budget); pass an object to
+     * tune `maxAttempts` / delays / `maxElapsedMs`; pass `false` to disable.
      */
-    readonly limits?: RunLimits;
+    readonly retry?: RetryOptions | false;
 }
 /**
- * The settle-consistent result of {@link AgentExecutor.run} / `runAndCollect`:
+ * The settle-consistent result of {@link AgentExecutor.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.
@@ -215,7 +70,7 @@ export interface RunResult {
     /** The run's error message when `!ok`. */
     readonly error?: string;
 }
-/** Options for {@link AgentExecutor.run} / `runAndCollect`. */
+/** Options for {@link AgentExecutor.run}. */
 export interface RunCollectOptions {
     /** Overall wait budget (ms) for the one-shot session turn to park. */
     readonly timeoutMs?: number;
@@ -226,7 +81,6 @@ export interface RunCollectOptions {
     readonly throwOnFailure?: boolean;
 }
 export type SessionInput = string | readonly string[];
-export type ChatInput = SessionInput;
 export interface SessionEnvironmentOptions extends Omit<PlatformEnvironmentInput, "envVars"> {
     readonly variables?: Readonly<Record<string, string>>;
     readonly secrets?: Readonly<Record<string, Secret>>;
@@ -236,13 +90,94 @@ export interface SessionOverrides {
     readonly timeout?: string;
     readonly maxSpendUsd?: number;
 }
-export interface SessionCreateOptions extends Omit<SubmitOptions, "prompt" | "webhook" | "environment" | "secretEnv" | "secrets" | "runtimeSize" | "parentRunId" | "limits" | "timeout"> {
+/**
+ * Options for opening a session (the low-level API) or a one-shot `run`.
+ * Everything the agent needs is spelled out at the call site:
+ *
+ *   - `model` / `system` — the agent's brief.
+ *   - `tools` — custom `Tool` bundles, skill-tools
+ *     (`Tools.fromSkillDir` / `Tools.fromSkillUrl`), and builtin tool-name
+ *     references; local composition instances are materialized to the hosted
+ *     asset store before the session lands.
+ *   - `agentsMd` / `files` — local composition instances
+ *     (`AgentsMd.fromContent` / `File.fromBytes`, …), materialized to the
+ *     hosted asset store before the session lands.
+ *   - `mcpServers` / `proxyEndpoints` — instances whose secrets are split into
+ *     the vaulted secrets channel server-side; the public submission carries
+ *     only the declarations.
+ *   - `apiKeys` — the BYOK provider key(s), keyed by provider. A key for the
+ *     selected provider is REQUIRED. The platform never holds a long-lived
+ *     provider key on your behalf.
+ */
+export interface SessionCreateOptions {
+    /**
+     * Upstream provider selector. Prefer naming it explicitly with the
+     * {@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;
+    /**
+     * Closed public model id. Prefer the {@link Models} symbol const, e.g.
+     * `Models.CLAUDE_HAIKU_4_5`.
+     */
+    readonly model: RunModel;
+    readonly system?: string;
+    /**
+     * Tools available to the agent. Each entry is a custom {@link Tool} bundle, a
+     * skill-tool ({@link SkillTool} from `Tools.fromSkillDir` / `Tools.fromSkillUrl`),
+     * or a BUILTIN tool reference — a bare name string, preferably
+     * `BuiltinTools.<name>` so a typo is a compile error.
+     */
+    readonly tools?: readonly (Tool | SkillTool | BuiltinToolName)[];
+    readonly agentsMd?: readonly AgentsMd[];
+    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.
+     */
+    readonly outputs?: {
+        readonly allowedDirs?: readonly string[];
+        readonly deniedDirs?: readonly string[];
+        readonly captureTimeoutMs?: number;
+        readonly maxFileBytes?: number;
+        readonly maxTotalBytes?: number;
+        readonly maxFiles?: number;
+    };
+    /**
+     * Whether to inject the standard builtin tool set
+     * ({@link DEFAULT_BUILTIN_TOOLS}). Omitted / `true` injects the standard
+     * builtins; `false` injects none. Cherry-pick a subset back via `tools`.
+     */
+    readonly includeBuiltinTools?: boolean;
+    /**
+     * Assistant-output granularity. `"buffered"` (default) delivers one event per
+     * assistant message; `"stream"` delivers per-token text deltas.
+     */
+    readonly outputMode?: OutputMode;
+    readonly metadata?: PlatformSubmission["metadata"];
+    readonly idempotencyKey?: string;
+    readonly proxyEndpoints?: readonly ProxyEndpoint[];
+    /** BYOK provider key(s), keyed by provider. */
     readonly apiKeys?: Partial<Record<RunProvider, string>>;
     readonly environment?: SessionEnvironmentOptions;
+    /**
+     * Managed runtime size. One of the closed {@link RuntimeSize} preset tokens.
+     * Prefer the {@link Sizes} symbol const.
+     */
     readonly runtime?: RuntimeSize;
     readonly overrides?: SessionOverrides;
+    /**
+     * Optional per-session callback URL. The platform delivers the terminal
+     * event to `webhook.url` at the settle-consistent barrier, signed
+     * Standard-Webhooks style (verify with {@link verifyAexWebhook}). The URL
+     * must be https.
+     */
+    readonly webhook?: {
+        readonly url: string;
+    };
 }
-export type ChatCreateOptions = SessionCreateOptions;
 export interface SessionSendOptions {
     readonly idempotencyKey?: string;
     readonly from?: number;
@@ -250,14 +185,12 @@ export interface SessionSendOptions {
     readonly idleTimeoutMs?: number;
     readonly pingIntervalMs?: number;
 }
-export type ChatSendOptions = SessionSendOptions;
 export interface SessionRunOptions extends SessionCreateOptions {
     readonly message: SessionInput;
     readonly deleteAfter?: boolean;
     readonly messageIdempotencyKey?: string;
     readonly stream?: Omit<SessionSendOptions, "idempotencyKey">;
 }
-export type ChatRunOptions = SessionRunOptions;
 export interface SessionTurnResult {
     readonly sessionId: string;
     readonly session: Session;
@@ -267,46 +200,155 @@ export interface SessionTurnResult {
     readonly events: readonly SessionEvent[];
     readonly outputs: readonly Output[];
 }
-export interface ChatTurnResult extends SessionTurnResult {
-}
 export interface SessionRunResult extends SessionTurnResult {
 }
-export interface ChatRunResult extends SessionRunResult {
-}
 export declare class SessionTurnStream implements AsyncIterable<SessionEvent> {
     #private;
     constructor(run: () => AsyncGenerator<SessionEvent, SessionTurnResult, void>);
     [Symbol.asyncIterator](): AsyncIterator<SessionEvent>;
     done(): Promise<SessionTurnResult>;
 }
-export declare const ChatTurnStream: typeof SessionTurnStream;
-export type ChatTurnStream = SessionTurnStream;
+/**
+ * Accessor over the session's decoded assistant messages. `session.messages()`
+ * returns this synchronously; each method fetches on call.
+ */
+export interface SessionMessages {
+    list(): Promise<readonly AssistantTextEntry[]>;
+    last(): Promise<AssistantTextEntry | undefined>;
+    first(): Promise<AssistantTextEntry | 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.
+ */
+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>;
+    archiveLink(options?: OutputLinkOptions): Promise<OutputLink>;
+    /** Download the events-namespace archive as a zip. */
+    download(options?: OutputDownloadOptions): Promise<Uint8Array>;
+}
+/**
+ * Accessor over the session's captured output files (`session.outputs()`):
+ * 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>;
+    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>;
+}
+/**
+ * Accessor over the session's webhook delivery ledger (`session.webhooks()`).
+ */
+export interface SessionWebhooks {
+    list(): Promise<readonly RunWebhookDelivery[]>;
+    redeliver(deliveryId: string): Promise<void>;
+}
 export declare class SessionHandle {
     #private;
-    constructor(http: HttpClient, session: Session);
+    constructor(http: HttpClient, session: Session, fetch?: FetchLike);
     get id(): string;
     get record(): Session;
     send(input: SessionInput, options?: SessionSendOptions): SessionTurnStream;
+    /**
+     * Re-send the last message on this session — the clean way to retry a turn a
+     * throttle or transient failure interrupted. By default it REUSES the previous
+     * message's idempotency key, so if the original turn actually landed
+     * server-side the replay de-duplicates instead of creating a second billable
+     * turn; pass a fresh `idempotencyKey` to force a brand-new turn.
+     */
+    replayLast(options?: SessionSendOptions): SessionTurnStream;
     suspend(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
     cancel(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
     resume(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
     delete(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<void>;
-    listEvents(): Promise<readonly SessionEvent[]>;
-    listOutputs(query?: OutputQuery): Promise<readonly Output[]>;
+    /**
+     * Accessor for the session's decoded assistant messages (buffered output
+     * mode: one entry per assistant message). `list()` returns them oldest-first;
+     * `last()`/`first()` return a single entry or `undefined` when empty.
+     */
+    messages(): SessionMessages;
+    /**
+     * Accessor for the session's event stream: the buffered `SessionEvent`
+     * snapshots (`list`/`last`/`first`), the polling `RunEvent` iterator
+     * (`stream`), the live coordinator envelope iterator (`streamEnvelopes`), and
+     * the events-namespace archive (`archiveLink`/`download`).
+     */
+    events(): SessionEvents;
+    /**
+     * Accessor for the session's captured output 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
+     * zip (no selector) or one file's raw bytes (with selector).
+     */
+    outputs(): SessionOutputs;
+    /**
+     * Accessor for the session's webhook delivery ledger: `list()` returns the
+     * delivery attempts; `redeliver(id)` re-sends the frozen payload under the
+     * same `webhook-id` so the consumer dedupes.
+     */
+    webhooks(): SessionWebhooks;
+    /** Re-read the session record from the server and store it as the current record. */
+    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`
+     * elapses first. Updates the stored record.
+     */
+    wait(options?: WaitForRunOptions): Promise<Session>;
+    /**
+     * Fetch the self-contained `RunUnit` for this session: parsed submission,
+     * attempts, indexed events, outputs, capture failures, proxy-call audit, and
+     * resolved skills. Use this when you need fields beyond the session record.
+     */
+    unit(): Promise<RunUnit>;
+    /**
+     * 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
+     * also write the bytes to a file path while still returning them.
+     */
+    download(options?: OutputDownloadOptions): Promise<Uint8Array>;
+    /** Download only the session record (the `metadata` namespace) as a zip. */
+    downloadMetadata(options?: OutputDownloadOptions): Promise<Uint8Array>;
 }
-export declare const ChatSession: typeof SessionHandle;
-export type ChatSession = SessionHandle;
 export declare class SessionClient {
     #private;
-    constructor(http: HttpClient, buildCreateRequest: (options: SessionCreateOptions) => Promise<SessionCreateRequest>);
+    constructor(http: HttpClient, buildCreateRequest: (options: SessionCreateOptions) => Promise<SessionCreateRequest>, fetch?: FetchLike);
     create(options: SessionCreateOptions): Promise<SessionHandle>;
     open(sessionId: string): Promise<SessionHandle>;
     get(sessionId: string): Promise<Session>;
     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()` /
+     * `.read(selector)` / `.download()` / … — so the workspace client and the
+     * 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>;
 }
-export declare const ChatClient: typeof SessionClient;
-export type ChatClient = SessionClient;
 export interface StreamEventsOptions {
     /** Poll interval in ms for the `RunEvent` snapshot loop. Default 1000. */
     readonly intervalMs?: number;
@@ -347,52 +389,12 @@ export type OutputLinkSelector = string | OutputFileSelector | OutputQuery;
 export interface OutputDownloadOptions {
     readonly to?: string;
 }
-/**
- * Workspace skill admin operations exposed under `client.skills`.
- *
- * New run submissions usually use `Skill.fromFiles(...)` or
- * `Skill.fromPath(...)` directly inside `submit`; the SDK materializes
- * those bytes to the hosted asset store before the run lands. This namespace is the read/delete
- * surface for workspace skill records and the internal transport used by the
- * legacy CLI upload command.
- */
-export declare class SkillsClient {
-    #private;
-    constructor(http: HttpClient);
-    list(): Promise<readonly SkillRecord[]>;
-    get(skillId: string): Promise<SkillRecord>;
-    delete(skillId: string): Promise<void>;
-    /**
-     * Lookup a live workspace skill by `(name, contentHash)`.
-     *
-     * Returns the matching `Skill` record or `null` when no live row
-     * carries that hash. The `contentHash` is the wire format
-     * `sha256:<hex>` returned by `hashSkillBundle` (and stored verbatim
-     * on every skill row). The hash space is unique enough that one
-     * row at most can match, so this is a single keyed lookup.
-     *
-     * Consumers can call this directly when they already have a hash in hand
-     * and want to know whether the skill is already persisted.
-     */
-    findByHash(args: {
-        readonly name: string;
-        readonly contentHash: string;
-    }): Promise<SkillRecord | null>;
-    /**
-     * Lookup a live workspace skill by `name`. Returns the matching
-     * `Skill` record or `null` when no live row carries that name.
-     * Implemented as a list-and-filter against the existing `/api/skills`
-     * endpoint — typical workspace skill counts are small enough that
-     * the cost is negligible.
-     */
-    findByName(name: string): Promise<SkillRecord | null>;
-}
 /**
  * Workspace AgentsMd admin operations exposed under `client.agentsMd`.
  *
- * New run submissions usually use `AgentsMd.fromContent(...)` or
- * `AgentsMd.fromPath(...)` directly inside `submit`; the SDK
- * materializes those bytes to the hosted asset store before the run lands. This namespace is
+ * New sessions usually use `AgentsMd.fromContent(...)` or
+ * `AgentsMd.fromPath(...)` directly on `openSession` / `run`; the SDK
+ * materializes those bytes to the hosted asset store before the session starts. This namespace is
  * the read/delete surface for persisted AgentsMd records.
  */
 export declare class AgentsMdClient {
@@ -405,9 +407,9 @@ export declare class AgentsMdClient {
 /**
  * Workspace File admin operations exposed under `client.files`.
  *
- * New run submissions usually use `File.fromPath(...)` or
- * `File.fromBytes(...)` directly inside `submit`; the SDK materializes
- * those bytes to the hosted asset store before the run lands. This namespace is the read/delete
+ * New sessions usually use `File.fromPath(...)` or
+ * `File.fromBytes(...)` directly on `openSession` / `run`; the SDK materializes
+ * those bytes to the hosted asset store before the session starts. This namespace is the read/delete
  * surface for persisted file records.
  */
 export declare class FilesClient {
@@ -419,17 +421,16 @@ export declare class FilesClient {
 }
 /**
  * Workspace secret management exposed under `client.secrets`, mirroring
- * `client.skills` / `client.files`.
+ * `client.agentsMd` / `client.files`.
  *
- * Lifecycle parity with assets/skills: a `Secret.value(...)` is per-run and
+ * Lifecycle parity with assets: a `Secret.value(...)` is per-run and
  * gone at terminal; `set` (or promoting an ephemeral via `secret.upload`)
  * persists a named, searchable workspace secret you can `get` (metadata),
- * `get_value` (audited value), `rotate`, `list`, and `delete`. The identity is the
- * `name`; the value rotates under that stable name.
+ * `rotate`, `list`, and `delete`. The identity is the `name`; the value rotates
+ * under that stable name.
  *
- * Values are write-only: `set`/`rotate` send the value in the request BODY (never
- * the URL); `get`/`list` return metadata only; `get_value` is the explicit audited
- * value read.
+ * Values are write-only through the public SDK: `set`/`rotate` send the value in
+ * the request BODY (never the URL); `get`/`list` return metadata only.
  */
 export declare class SecretsClient {
     #private;
@@ -443,8 +444,6 @@ export declare class SecretsClient {
     list(): Promise<readonly SecretRecord[]>;
     /** Metadata for one workspace secret by name. Never returns the value. */
     get(name: string): Promise<SecretRecord>;
-    /** Audited value read — the preferred path that returns a workspace secret value. */
-    get_value(name: string): Promise<SecretReveal>;
     /** Replace the value of an existing workspace secret; bumps its version. */
     rotate(args: {
         readonly name: string;
@@ -476,12 +475,10 @@ export declare class SecretsClient {
  */
 export declare class AgentExecutor {
     #private;
-    readonly skills: SkillsClient;
     readonly agentsMd: AgentsMdClient;
     readonly files: FilesClient;
     readonly secrets: SecretsClient;
     readonly sessions: SessionClient;
-    readonly chat: ChatClient;
     constructor(options: AgentExecutorOptions);
     /**
      * Internal: satisfies the `SecretUploader` surface so a
@@ -497,9 +494,10 @@ export declare class AgentExecutor {
     }>;
     /**
      * Internal: materialize raw bytes to the content-addressable asset store
-     * (`/assets/presign` → PUT → `/assets/finalize`). Used by `Skill.upload(this)`
-     * to pre-upload a draft skill bundle so a later run carries only a plain
-     * `kind:"asset"` ref. NOT part of the public API.
+     * (`/assets/presign` → PUT → `/assets/finalize`). Used by the session-create
+     * prepare step to upload draft skill-tool / tool / agentsMd / file bundles so
+     * the wire submission carries only plain `kind:"asset"` / `kind:"skill"` refs.
+     * NOT part of the public API.
      */
     _uploadAsset(args: {
         readonly bytes: Uint8Array;
@@ -514,140 +512,8 @@ export declare class AgentExecutor {
      * so callers can resume later with `openSession(runId)`.
      */
     run(options: SessionRunOptions, opts?: RunCollectOptions): Promise<RunResult>;
-    /**
-     * Explicit, discoverable alias for {@link run}: open a one-shot session turn
-     * and collect the full {@link RunResult} in one call.
-     */
-    runAndCollect(options: SessionRunOptions, opts?: RunCollectOptions): Promise<RunResult>;
     openSession(options: SessionCreateOptions): Promise<SessionHandle>;
     openSession(sessionId: string): Promise<SessionHandle>;
-    /**
-     * Submit a run and return its run id immediately. Use that id with
-     * `wait`, `stream`, `outputs`, `download`, `cancel`, or `delete`.
-     *
-     * The SDK splits `mcpServers[i].headers` into `secrets.mcpServers`
-     * and `proxyEndpoints[i]` auth values into `secrets.proxyEndpointAuth`
-     * before sending so credentials never enter the hashed submission or
-     * the run snapshot.
-     *
-     * Unstaged inline skills / agentsMd / files (`Skill.fromFiles` /
-     * `Skill.fromPath` / `AgentsMd.fromContent` / `File.fromBytes` without a
-     * prior `.upload`) are auto-uploaded to the content-addressable asset
-     * store (`/assets/presign` → PUT → `/assets/finalize`) before `POST /runs`,
-     * deduped by content hash, and referenced in the submission as plain
-     * `{ kind:"asset" }` refs — identical to a pre-staged `.upload(client)`.
-     */
-    submit(options: SubmitOptions): Promise<string>;
-    getRun(runId: string): Promise<Run>;
-    /** Short alias for `getRun`. */
-    get(runId: string): Promise<Run>;
-    /**
-     * List the runs in this workspace, most-recent first, one page at a time.
-     * The workspace is derived server-side from the API token, so this only ever
-     * enumerates your own runs. Pass `query.cursor` (from a prior page's
-     * `nextCursor`) to page; omit it for the first page. Returns public-safe
-     * {@link RunSummary} rows — the full submission stays behind `getRunUnit`.
-     *
-     * This is the workspace-wide discovery entry point: combine it with
-     * `listOutputs` / `readOutputText` to reach any run's deliverables.
-     */
-    listRuns(query?: RunListQuery): Promise<RunListPage>;
-    /**
-     * Find output files across runs by filename / extension / content type.
-     * Returns lean REFERENCE hits (runId, outputId, filename, size, content type)
-     * — never bytes; fetch content with {@link readOutputText}. Scope the search
-     * to a corpus with `query.runIds`; omit it to scan the whole workspace (needs
-     * the owner-gated `listRuns`). Composed client-side for the MVP (per-run
-     * `listOutputs` + the contracts output filter), so it works against any
-     * already-terminal run with no new server endpoint. Bounded by
-     * `query.limit` (default 100) — for very large corpora prefer the deferred
-     * server-side index.
-     */
-    searchOutputs(query?: OutputSearchQuery): Promise<OutputSearchPage>;
-    /**
-     * Fetch the self-contained `RunUnit`: parsed submission inputs,
-     * attempts, indexed events (inline + cursor for the tail), raw
-     * provider-event Storage manifest, outputs, capture failures,
-     * proxy-call audit, pinned workspace skills, provider skills,
-     * inline skills. Backed by the same endpoint as `getRun` but
-     * typed against the full wire shape — use this when you need
-     * fields beyond `{id, status, timestamps, usage}`.
-     */
-    getRunUnit(runId: string): Promise<RunUnit>;
-    /** Short alias for `getRunUnit`. */
-    getUnit(runId: string): Promise<RunUnit>;
-    listEvents(runId: string): Promise<readonly RunEvent[]>;
-    /** Short alias for `listEvents`. */
-    events(runId: string): Promise<readonly RunEvent[]>;
-    /**
-     * Yield run events (the `RunEvent` snapshot shape) as they arrive, by
-     * polling the coordinator-backed `/events` endpoint until the run reaches
-     * a terminal state, the signal aborts, or the caller breaks the iterator.
-     *
-     * For the live, low-latency envelope stream prefer {@link streamEnvelopes}
-     * (coordinator WebSocket). This polling form stays for consumers that want
-     * the loose `RunEvent` shape without a WS.
-     */
-    streamEvents(runId: string, options?: StreamEventsOptions): AsyncIterable<RunEvent>;
-    /** Short alias for `streamEvents`. */
-    stream(runId: string, options?: StreamEventsOptions): AsyncIterable<RunEvent>;
-    /**
-     * Stream the unified {@link AexEvent} envelope live over the coordinator
-     * WebSocket. The hosted API's ticket broker authorizes the connection (workspace
-     * token → short-lived coordinator ticket); the shared client replays from
-     * the cursor, tails live, and resumes exactly-once across reconnects. The
-     * ticket is re-minted on each (re)connect so a long run never outlives it.
-     */
-    streamEnvelopes(runId: string, options?: StreamEnvelopesOptions): AsyncIterable<AexEvent>;
-    /**
-     * Poll the run record until it reaches a terminal status (succeeded,
-     * failed, terminated). Throws if `timeoutMs` elapses first.
-     */
-    waitForRun(runId: string, options?: WaitForRunOptions): Promise<Run>;
-    /** Short alias for `waitForRun`. */
-    wait(runId: string, options?: WaitForRunOptions): Promise<Run>;
-    listOutputs(runId: string, query?: OutputQuery): Promise<readonly Output[]>;
-    /** Short alias for `listOutputs`. */
-    outputs(runId: string, query?: OutputQuery): Promise<readonly Output[]>;
-    findOutputs(runId: string, query: OutputQuery): Promise<readonly Output[]>;
-    findOutput(runId: string, query: OutputQuery): Promise<Output | null>;
-    outputLink(runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
-    createOutputLink(runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
-    fetchOutput(runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<Response>;
-    /**
-     * Read ONE output file as byte-capped, decoded UTF-8 text. Streams the file and
-     * STOPS at `options.maxBytes` (default 50 KB, ceiling 10 MB), so a huge
-     * deliverable never fully buffers — ideal for handing a run's output to an LLM
-     * tool. Check `result.truncated` before treating the text as complete; pass
-     * `options.grep` to keep only matching lines. Select by `{ path }` or `{ id }`,
-     * same as `downloadOutput`.
-     */
-    readOutputText(runId: string, selector: OutputFileSelector, options?: ReadOutputTextOptions): Promise<OutputText>;
-    eventArchiveLink(runId: string, options?: OutputLinkOptions): Promise<OutputLink>;
-    /**
-     * Download captured deliverables. Omit `selector` to receive the full
-     * outputs namespace as a zip; pass an id, Output object, or path selector
-     * to receive one file's raw bytes.
-     */
-    downloadOutput(runId: string, options?: OutputDownloadOptions): Promise<Uint8Array>;
-    downloadOutput(runId: string, selector: undefined, options?: OutputDownloadOptions): Promise<Uint8Array>;
-    downloadOutput(runId: string, selector: OutputFileSelector, options?: OutputDownloadOptions): Promise<Uint8Array>;
-    cancelRun(runId: string): Promise<void>;
-    /** Short alias for `cancelRun`. */
-    cancel(runId: string): Promise<void>;
-    deleteRun(runId: string): Promise<void>;
-    /** Short alias for `deleteRun`. */
-    delete(runId: string): Promise<void>;
-    /**
-     * List a run's webhook delivery attempts (the per-run delivery ledger).
-     * Empty when the run carried no `webhook` or has not yet terminated.
-     */
-    getRunWebhookDeliveries(runId: string): Promise<readonly RunWebhookDelivery[]>;
-    /**
-     * Manually re-trigger a run's webhook delivery: re-sends the frozen payload
-     * with the SAME `webhook-id` so the consumer dedupes.
-     */
-    redeliverRunWebhook(runId: string, deliveryId: string): Promise<void>;
     /**
      * Delete a workspace asset blob from the shared content-addressed store
      * (`assets/<workspaceId>/<hash>`). Accepts `sha256:<hex>` or a bare
@@ -655,21 +521,6 @@ export declare class AgentExecutor {
      */
     deleteWorkspaceAsset(hash: string): Promise<void>;
     whoami(): Promise<WhoAmI>;
-    /**
-     * Download EVERYTHING public about a run as one zip, assembled client-side
-     * from the public read endpoints (`getRun` + `listEvents` +
-     * `listOutputs` + per-output `/download`). Organised into the namespace
-     * folders `metadata/`, `events/`, and `outputs/`, plus a `manifest.json`.
-     * Pass `to` to also write the
-     * bytes to a file path while still returning the bytes.
-     */
-    download(runId: string, options?: OutputDownloadOptions): Promise<Uint8Array>;
-    /** Download only the run's deliverables (the `outputs` namespace) as a zip. */
-    downloadOutputs(runId: string, options?: OutputDownloadOptions): Promise<Uint8Array>;
-    /** Download only the indexed event archive (the `events` namespace) as a zip. */
-    downloadEvents(runId: string, options?: OutputDownloadOptions): Promise<Uint8Array>;
-    /** Download only the run record (the `metadata` namespace) as a zip. */
-    downloadMetadata(runId: string, options?: OutputDownloadOptions): Promise<Uint8Array>;
 }
 /** Canonical SDK client name. `AgentExecutor` remains as a compatibility alias. */
 export declare class Aex extends AgentExecutor {