@aexhq/sdk 0.28.1 → 0.30.0

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-0386d2625bfa4f8aea426cffc3bf21546c48b33b7134eb7cd4bbfefdc2d69d96  cli.mjs
+88682d1f64442fabb34e7f3645f950c2a109b192183b100cd75dbaf92fd8f385  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 RunRegion, 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 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 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 Region, type SecretRecord, type SecretReveal, type RunUnit, type BuiltinToolName, type RuntimeSize, type RuntimeKind, 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,8 +40,9 @@ 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
+ *   - `apiKey` / `credentials` / `secrets` — the BYOK provider key(s). A key for
+ *     the selected provider is REQUIRED; the simplest call passes just `apiKey`.
+ *     Use `credentials` (or `secrets.apiKeys`) to 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.
@@ -77,11 +78,11 @@ export interface SubmitOptions {
      */
     readonly runtime?: RuntimeKind;
     /**
-     * Optional hosted-platform placement token for this run. These are product
-     * region tokens, not exact city guarantees; omit to let the platform infer a
-     * configured region and fall back when no hint matches.
+     * 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?: RunRegion;
+    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
@@ -121,7 +122,7 @@ export interface SubmitOptions {
     /**
      * Managed runtime size. One of the closed {@link RuntimeSize} preset tokens.
      * Prefer the {@link RuntimeSizes} symbol const, e.g.
-     * `RuntimeSizes.SHARED_2X_2GB`.
+     * `RuntimeSizes.SHARED_2X_8GB`.
      */
     readonly runtimeSize?: RuntimeSize;
     /**
@@ -171,7 +172,26 @@ export interface SubmitOptions {
      * typing UIs.
      */
     readonly outputMode?: OutputMode;
-    readonly secrets: PlatformInlineSecrets;
+    /**
+     * Single-provider BYOK key sugar — the key for the run's selected `provider`.
+     * The simplest call passes just `apiKey` (no nested `secrets` envelope). When
+     * several sources name a key for the same provider they must agree (else submit
+     * throws); resolution precedence is
+     * `secrets.apiKeys[provider] ?? secrets.apiKey ?? credentials[provider] ?? apiKey`.
+     */
+    readonly apiKey?: string;
+    /**
+     * Multi-provider BYOK key map — the clean way to supply keys for more than one
+     * provider (e.g. so a subagent spawned with a different-family model inherits a
+     * key server-side). Folded into the `secrets.apiKeys` wire shape.
+     */
+    readonly credentials?: Partial<Record<RunProvider, string>>;
+    /**
+     * Advanced inline secrets bundle (per-provider `apiKeys`, MCP headers, proxy
+     * auth, env secrets). OPTIONAL — the common case uses `apiKey` / `credentials`.
+     * `secrets.apiKey` / `secrets.apiKeys` keep working unchanged.
+     */
+    readonly secrets?: PlatformInlineSecrets;
     readonly idempotencyKey?: string;
     /**
      * Lineage parent (agent-session §9). When set, the server admits this run as
@@ -205,6 +225,42 @@ export interface SubmitOptions {
 }
 /** @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;
@@ -463,15 +519,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 +570,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