@aexhq/sdk 0.13.6

package/dist/cli.mjs.sha256

@@ -0,0 +1 @@
+bbc00f3784013aefc17bd7b5253652f3290d1fcdef98a2302d32befb4f6bf2ec  cli.mjs

package/dist/client.d.ts

@@ -0,0 +1,460 @@
+import { HttpClient, type AexEvent, type AgentsMdRecord, type CredentialMode, type DebugSink, type FetchLike, type FileRecord, type Output, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type Run, type RunEvent, type RunProvider, type RunUnit, type RuntimeSize, type RuntimeKind, type SignedOutputLink, type Skill as SkillRecord, type WhoAmI } from "./_contracts/index.js";
+import { AgentsMd } from "./agents-md.js";
+import { File } from "./file.js";
+import { McpServer } from "./mcp-server.js";
+import { ProxyEndpoint } from "./proxy-endpoint.js";
+import { Skill } from "./skill.js";
+export interface AexClientOptions {
+    /** Workspace-scoped SDK API token. */
+    readonly apiToken: string;
+    /**
+     * API plane root, e.g. `https://aex.example.com`. Optional —
+     * defaults to the canonical hosted URL (`https://api.aex.dev`).
+     * Override for local, staging, or other hosted aex API planes.
+     */
+    readonly baseUrl?: string;
+    /** Optional `fetch` override for testing. */
+    readonly fetch?: FetchLike;
+    /**
+     * Local debug output. `true` prints a redacted one-line trace per HTTP
+     * request to stderr (method, path, status, elapsed); pass a function to
+     * 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.<provider>.apiKey` — REQUIRED for the selected provider.
+ *     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 SubmitRunOptions {
+    /**
+     * Credential source for upstream provider access. Omitted defaults to
+     * `"byok"`, which requires `secrets.<provider>.apiKey` as today.
+     * `"managed"` is reserved for paid managed-key mode and currently fails
+     * closed until the hosted private implementation is wired.
+     */
+    readonly credentialMode?: CredentialMode;
+    /**
+     * Provider selector. Optional — defaults to
+     * {@link DEFAULT_RUN_PROVIDER} (`"anthropic"`). The call site must
+     * supply the matching `secrets.<provider>.apiKey` and MUST NOT
+     * supply any other provider's secret block.
+     */
+    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;
+    readonly model: string;
+    readonly system?: string;
+    readonly prompt: string | readonly string[];
+    readonly skills?: readonly Skill[];
+    readonly agentsMd?: readonly AgentsMd[];
+    readonly files?: readonly File[];
+    readonly mcpServers?: readonly McpServer[];
+    readonly environment?: PlatformSubmission["environment"];
+    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_2GB`.
+     */
+    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[];
+    };
+    /**
+     * Override the managed runtime builtin extensions enabled inside the runner.
+     *
+     * - Omitted (default): the runner enables `["developer"]` which gives
+     *   the agent `shell`, `write`, `edit`, and `tree` tools (bash, grep
+     *   via shell, file read via shell or editor, file edit).
+     * - Empty array: the agent runs with zero builtin extensions —
+     *   useful for pure-MCP setups where every tool comes from a
+     *   submitted `mcpServers` entry.
+     * - Custom list: e.g. `["developer", "computercontroller"]` to add
+     *   web search alongside the default shell/edit toolkit.
+     *
+     * Validation: each entry matches `/^[a-z][a-z0-9_-]{0,63}$/`, max 16
+     * entries, deduplicated server-side.
+     */
+    readonly builtins?: readonly string[];
+    readonly secrets: PlatformInlineSecrets;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface StreamEventsOptions {
+    /** Poll interval in ms for the `RunEvent` snapshot loop. Default 1000. */
+    readonly intervalMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface StreamEnvelopesOptions {
+    /** Starting cursor — events with `sequence >= from` are delivered. Default 0. */
+    readonly from?: number;
+    readonly signal?: AbortSignal;
+}
+export interface WaitForRunOptions {
+    readonly intervalMs?: number;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export type OutputFilePathMatch = "exact" | "suffix";
+export interface OutputFilePathSelector {
+    readonly path: string;
+    readonly match?: OutputFilePathMatch;
+}
+export interface OutputFileIdSelector {
+    readonly id: string;
+}
+export type OutputFileSelector = Output | OutputFileIdSelector | OutputFilePathSelector;
+export interface OutputDownloadOptions {
+    readonly to?: string;
+}
+/**
+ * One captured debug artifact returned by {@link AexClient.getRunDebugLogs}.
+ *
+ *   - `filename` is the path under `runs/{runId}/logs/` — leading
+ *     `runtime/` for runtime logs and `host/` for host logs.
+ *   - `text` is populated when the content type looks textual
+ *     (`text/*`, `application/json`); decoded as UTF-8.
+ *   - `bytesBase64` is always present so a caller that wants raw bytes
+ *     (e.g. piping into a file) can use it uniformly across textual
+ *     and binary artifacts.
+ */
+export interface RunDebugLog {
+    readonly filename: string;
+    readonly sizeBytes: number;
+    readonly contentType: string;
+    readonly createdAt: string;
+    readonly text?: string;
+    readonly bytesBase64: string;
+}
+export interface RunDebugLogError {
+    readonly filename: string;
+    readonly message: string;
+}
+export interface RunDebugLogs {
+    readonly runId: string;
+    readonly logs: ReadonlyArray<RunDebugLog>;
+    readonly errors: ReadonlyArray<RunDebugLogError>;
+}
+/**
+ * Workspace skill admin operations exposed under `client.skills`.
+ *
+ * New run submissions usually use `Skill.fromFiles(...)` or
+ * `Skill.fromPath(...)` directly inside `submitRun`; 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>;
+    /**
+     * 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`.
+ *
+ * New run submissions usually use `AgentsMd.fromContent(...)` or
+ * `AgentsMd.fromPath(...)` directly inside `submitRun`; the SDK
+ * materializes those bytes to the hosted asset store before the run lands. This namespace is
+ * the read/delete surface for persisted AgentsMd records plus an internal
+ * upload transport retained for legacy callers.
+ */
+export declare class AgentsMdClient {
+    #private;
+    constructor(http: HttpClient);
+    list(): Promise<readonly AgentsMdRecord[]>;
+    get(agentsMdId: string): Promise<AgentsMdRecord>;
+    delete(agentsMdId: string): Promise<void>;
+    /**
+     * Internal: post an AgentsMd markdown string to the BFF.
+     * NOT part of the public API.
+     */
+    _uploadAgentsMd(args: {
+        readonly name: string;
+        readonly content: string;
+    }): Promise<AgentsMdRecord>;
+}
+/**
+ * Workspace File admin operations exposed under `client.files`.
+ *
+ * New run submissions usually use `File.fromPath(...)` or
+ * `File.fromBytes(...)` directly inside `submitRun`; the SDK materializes
+ * those bytes to the hosted asset store before the run lands. This namespace is the read/delete
+ * surface for persisted file records plus an internal upload transport
+ * retained for legacy callers.
+ */
+export declare class FilesClient {
+    #private;
+    constructor(http: HttpClient);
+    list(): Promise<readonly FileRecord[]>;
+    get(fileId: string): Promise<FileRecord>;
+    delete(fileId: string): Promise<void>;
+    /**
+     * Internal: post a pre-bundled file zip to the BFF.
+     * NOT part of the public API.
+     */
+    _uploadFile(args: {
+        readonly name: string;
+        readonly bytes: Uint8Array;
+    }): Promise<FileRecord>;
+}
+/**
+ * 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 SDK never asks the caller for a workspace id — workspace identity
+ * is derived server-side from the API token on every request. Use
+ * `client.whoami()` if you want to introspect which workspace the
+ * token resolves to.
+ */
+export declare class AexClient {
+    #private;
+    readonly skills: SkillsClient;
+    readonly agentsMd: AgentsMdClient;
+    readonly files: FilesClient;
+    constructor(options: AexClientOptions);
+    /**
+     * 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` no longer
+     * exposes `.upload()`/`.fromId()`. 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
+     * `AgentsMdClient._uploadAgentsMd`. NOT part of the public API.
+     */
+    _uploadAgentsMd(args: {
+        readonly name: string;
+        readonly content: string;
+    }): Promise<AgentsMdRecord>;
+    /**
+     * Internal: a `File.upload(this)` shortcut that bypasses
+     * `client.files` indirection. Forwarded to
+     * `FilesClient._uploadFile`. NOT part of the public API.
+     */
+    _uploadFile(args: {
+        readonly name: string;
+        readonly bytes: Uint8Array;
+    }): Promise<FileRecord>;
+    /**
+     * Submit a run and wait for it to reach a terminal state. Returns the
+     * final `Run` record. For long-running flows, prefer `submitRun` +
+     * `stream(runId)` + `wait(runId)`.
+     */
+    run(options: SubmitRunOptions): Promise<Run>;
+    /**
+     * 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 (`Skill.fromFiles` / `Skill.fromPath`
+     * without a prior `.upload`) are accepted: the SDK switches to a
+     * multipart body that carries the canonical zip bytes alongside the
+     * JSON submission. The dashboard BFF ingests each one through the
+     * standard workspace-skill upload pipeline (dedup by content hash;
+     * upload via the existing two-phase pending → ready flow) and
+     * rewrites the run's `skills[]` to reference the resulting `skl_*`
+     * ids. The bytes persist on aex; the user can browse and
+     * download the resulting workspace skill from the dashboard.
+     */
+    submitRun(options: SubmitRunOptions): Promise<string>;
+    getRun(runId: string): Promise<Run>;
+    /** Short alias for `getRun`. */
+    get(runId: string): Promise<Run>;
+    /**
+     * 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 Worker'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): Promise<readonly Output[]>;
+    /** Short alias for `listOutputs`. */
+    outputs(runId: string): Promise<readonly Output[]>;
+    createOutputLink(runId: string, outputId: string): Promise<SignedOutputLink>;
+    /**
+     * 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>;
+    /**
+     * Bundle the per-run debug artifacts aex captures automatically:
+     *
+     *   - `runtime/{stdout,stderr,args}.log` — runtime process diagnostics.
+     *   - `host/...` — managed host logs when the platform includes them.
+     * These all live in the run's `logs` namespace (`runs/<id>/logs/`).
+     * Each is downloaded through the gated `/logs/:id/download` endpoint,
+     * decoded as UTF-8 text when the content type looks textual, and
+     * surfaced as raw bytes (base64) otherwise. The call is best-effort: a
+     * download failure for one file does not block the others; the failing
+     * entry lands in `errors` with the underlying message.
+     *
+     * Use this when a run failed or behaved oddly and you want all the
+     * post-mortem material in one round-trip — no need to wire
+     * `listOutputs` + `createOutputLink` by hand.
+     */
+    getRunDebugLogs(runId: string): Promise<RunDebugLogs>;
+    /** Short alias for `getRunDebugLogs`. */
+    debugLogs(runId: string): Promise<RunDebugLogs>;
+    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>;
+    /**
+     * 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.
+     */
+    deleteWorkspaceAsset(hash: string): Promise<void>;
+    whoami(): Promise<WhoAmI>;
+    /**
+     * Download EVERYTHING about a run as one zip, assembled client-side
+     * from the public read endpoints (`getRun` + `listEvents` +
+     * `listOutputs` + per-output `/download`). Organised into the four
+     * namespace folders: `metadata/`, `events/`, `outputs/` (deliverables),
+     * `logs/` (`runtime/`, `host/`, `provider-proxy/`, `control-plane/`
+     * diagnostics), 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 platform diagnostics (the `logs` namespace) as a zip. */
+    downloadLogs(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>;
+}
+export type { PlatformProxyEndpoint, PlatformProxyEndpointAuth };