@aexhq/sdk 0.29.0 → 0.31.0

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-03e2640ecfc2afaed33effd74cb0fb3cea62e049193e566c16eb3d80340ddfff  cli.mjs
+6fdbb02bcedc98dc959c46f14b44bc0d061c799e01627d2550e58980d954e722  cli.mjs

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type CredentialMode, 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 PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type PlatformPostHookInput, type Run, type RunModel, type RunEvent, type RunLimits, type RunWebhookDelivery, type RunProvider, type Region, type SecretRecord, type SecretReveal, type RunUnit, type BuiltinToolName, type RuntimeSize, type RuntimeKind, type Skill as SkillRecord, type WhoAmI } from "./_contracts/index.js";
+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 PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type PlatformPostHookInput, 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 WhoAmI } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { type UploadedAsset } from "./asset-upload.js";
 import { File } from "./file.js";
@@ -40,29 +40,22 @@ export interface AgentExecutorOptions {
  *     secret is bundled into the constructor and split into
  *     `secrets.proxyEndpointAuth` server-side; the public submission
  *     only carries the declaration (`{ name, baseUrl, authShape, … }`).
- *   - `secrets.apiKey` or `secrets.apiKeys[provider]` — REQUIRED: the provider
- *     key for the selected provider. `apiKeys` MAY carry keys for additional
- *     providers so subagents spawned with a different-family model can use them
- *     (the child inherits the parent's keys server-side). The platform never
- *     holds a long-lived provider key on your behalf.
+ *   - `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 {
-    /**
-     * Credential source for upstream provider access. Omitted defaults to
-     * `"byok"`, which requires `secrets.apiKey` or
-     * `secrets.apiKeys[provider]`.
-     */
-    readonly credentialMode?: CredentialMode;
     /**
      * 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.apiKey` or `secrets.apiKeys[provider]`.
+     * `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
@@ -70,18 +63,6 @@ export interface SubmitOptions {
      * throws.
      */
     readonly provider?: RunProvider;
-    /**
-     * Optional runtime selector. Omit it or pass `"managed"`; both run on
-     * the managed runtime through the hosted BYOK provider-proxy. `"native"`
-     * is no longer accepted.
-     */
-    readonly runtime?: RuntimeKind;
-    /**
-     * Optional hosted-platform placement region for this run. These are
-     * product-level tokens, not exact city guarantees; omit to let the platform
-     * infer a configured region and fall back when no hint matches.
-     */
-    readonly region?: Region;
     /**
      * 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
@@ -171,7 +152,11 @@ export interface SubmitOptions {
      * typing UIs.
      */
     readonly outputMode?: OutputMode;
-    readonly secrets: PlatformInlineSecrets;
+    /**
+     * 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
@@ -203,8 +188,42 @@ export interface SubmitOptions {
     readonly limits?: RunLimits;
     readonly signal?: AbortSignal;
 }
-/** @deprecated Renamed to {@link SubmitOptions}. Kept for one release. */
-export type SubmitRunOptions = SubmitOptions;
+/**
+ * The settle-consistent result of {@link AgentExecutor.run} / `runAndCollect`:
+ * the terminal run record plus its settle-bracketed events, decoded trace,
+ * assistant text, and captured outputs — everything a "do it and give me the
+ * result" caller needs without hand-rolling a poll loop.
+ */
+export interface RunResult {
+    readonly runId: string;
+    /** The full terminal run record (status, costTelemetry, timings). */
+    readonly run: Run;
+    readonly status: string;
+    /** `true` when `status === "succeeded"`. */
+    readonly ok: boolean;
+    /** The assistant's final text (decoded over the settled events). */
+    readonly text: string;
+    /** The settle-bracketed event stream (RUN_STARTED … terminal). */
+    readonly events: readonly RunEvent[];
+    /** Decoded view of the events: tool calls + usage + assistant text. */
+    readonly trace: RunTrace;
+    /** The run's captured output files. */
+    readonly outputs: readonly Output[];
+    /** Aggregate token usage when the deployment exposes it on the record. */
+    readonly usage?: UsageSummary;
+    /** Settle-time showback estimate (USD), from `run.costTelemetry`. */
+    readonly costUsd?: number;
+    /** The run's error message when `!ok`. */
+    readonly error?: string;
+}
+/** Options for {@link AgentExecutor.run} / `runAndCollect`. */
+export interface RunCollectOptions {
+    /** Overall wait budget (ms) for the run to reach a terminal record. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Throw a {@link RunStateError} when the run does not succeed. Default false. */
+    readonly throwOnFailure?: boolean;
+}
 export interface StreamEventsOptions {
     /** Poll interval in ms for the `RunEvent` snapshot loop. Default 1000. */
     readonly intervalMs?: number;
@@ -284,14 +303,6 @@ export declare class SkillsClient {
      * the cost is negligible.
      */
     findByName(name: string): Promise<SkillRecord | null>;
-    /**
-     * Internal: post a pre-bundled skill zip to the BFF. Only
-     * `Skill.upload` calls this. NOT part of the public API.
-     */
-    _uploadSkillBundle(args: {
-        readonly name: string;
-        readonly body: Uint8Array;
-    }): Promise<SkillRecord>;
 }
 /**
  * Workspace AgentsMd admin operations exposed under `client.agentsMd`.
@@ -405,22 +416,6 @@ export declare class AgentExecutor {
     readonly files: FilesClient;
     readonly secrets: SecretsClient;
     constructor(options: AgentExecutorOptions);
-    /**
-     * Internal: forwards to `SkillsClient._uploadSkillBundle`. NOT part of
-     * the public API.
-     *
-     * NOTE (tech-debt): this is part of the legacy workspace-skill upload
-     * surface (`SkillsClient` + `operations.createSkillBundle` + the TUS
-     * chunked path in asset-upload.ts). The live submit path materializes
-     * inline skills via `uploadAsset` instead; `Skill.upload(client)`
-     * pre-stages a draft explicitly for reuse. This surface is retained
-     * pending a deliberate deprecation pass (it still threads into the CLI
-     * host commands), tracked in the remediation plan as item 4a.
-     */
-    _uploadSkillBundle(args: {
-        readonly name: string;
-        readonly body: Uint8Array;
-    }): Promise<SkillRecord>;
     /**
      * Internal: an `AgentsMd.upload(this)` shortcut that bypasses
      * `client.agentsMd` indirection. Forwarded to
@@ -463,15 +458,26 @@ export declare class AgentExecutor {
         readonly contentType?: string;
     }): Promise<UploadedAsset>;
     /**
-     * Submit a run and wait until its RECORD is terminal — the settle-consistent
-     * "do it and give me the result" primitive. Returns the final `Run`, so on
-     * resolve a subsequent `getRun`/`listOutputs` is guaranteed consistent (it
-     * polls `getRun` via {@link waitForRun}, NOT the RUN_FINISHED event, which the
-     * runner emits before the platform commits the record). For long-running flows
-     * that need live events, prefer `submit` + `streamEnvelopes(runId, {
-     * settleConsistent: true })`, or `submit` + `stream(runId)` + `wait(runId)`.
+     * Submit a run, wait until its RECORD is terminal, and collect the full
+     * {@link RunResult} — the settle-consistent "do it and give me the result"
+     * primitive. Folds the poll loop every consumer hand-rolled into one call:
+     * submit → {@link waitForRun} (polls `getRun`, NOT the earlier RUN_FINISHED
+     * event) → poll `listEvents` until the snapshot is settle-bracketed
+     * (RUN_STARTED + a terminal event present) → `listOutputs` → decode the trace
+     * and assistant text. On resolve, `getRun`/`listOutputs` are guaranteed
+     * consistent.
+     *
+     * Uses polling (portable across backends), NOT the coordinator WebSocket. By
+     * default a failed run resolves with `ok: false` and a populated `error`; pass
+     * `{ throwOnFailure: true }` to throw instead. For live events prefer `submit`
+     * + `streamEnvelopes(runId, { settleConsistent: true })`.
+     */
+    run(options: SubmitOptions, opts?: RunCollectOptions): Promise<RunResult>;
+    /**
+     * Explicit, discoverable alias for {@link run}: submit, wait, and collect the
+     * full {@link RunResult} in one call.
      */
-    run(options: SubmitOptions): Promise<Run>;
+    runAndCollect(options: SubmitOptions, opts?: RunCollectOptions): Promise<RunResult>;
     /**
      * Submit a run and return its run id immediately. Use that id with
      * `wait`, `stream`, `outputs`, `download`, `cancel`, or `delete`.
@@ -503,6 +509,18 @@ export declare class AgentExecutor {
      * `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
@@ -532,7 +550,7 @@ export declare class AgentExecutor {
     stream(runId: string, options?: StreamEventsOptions): AsyncIterable<RunEvent>;
     /**
      * Stream the unified {@link AexEvent} envelope live over the coordinator
-     * WebSocket. The Worker's ticket broker authorizes the connection (workspace
+     * 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.