@aexhq/sdk 0.13.6

package/dist/_contracts/operations.d.ts

@@ -0,0 +1,237 @@
+import type { HttpClient } from "./http.js";
+import type { RunUnit } from "./run-unit.js";
+import type { AgentsMdRecord, FileRecord, Output, OutputFileDownload, OutputFileSelector, Run, RunEvent, SignedOutputLink, Skill, WhoAmI } from "./runtime-types.js";
+import type { PlatformRunSubmissionInput } from "./submission.js";
+/**
+ * The single source of truth for SDK<->BFF transport. The SDK class
+ * AND the CLI subcommands both call these functions; neither
+ * surface re-implements HTTP requests against the dashboard.
+ *
+ * Every function takes an HttpClient (so callers control auth + fetch
+ * injection) and returns parsed responses.
+ *
+ * Workspace identity is derived server-side from the API token on
+ * every request; callers do not pass `workspaceId`.
+ */
+export declare function getRun(http: HttpClient, runId: string): Promise<Run>;
+/**
+ * Strongly-typed accessor for the full self-contained run unit:
+ * parsed submission inputs, attempts, indexed events (with
+ * pagination cursor for large runs), raw-event Storage manifest,
+ * outputs, capture failures, proxy-call audit, pinned skills,
+ * provider skills, inline skills.
+ *
+ * Backed by the same `GET /api/runs/:runId` endpoint that
+ * `getRun` calls; this variant just narrows the return type to
+ * the documented wire shape. Prefer this for new code; `getRun`
+ * stays for callers that only need the loose record.
+ */
+export declare function getRunUnit(http: HttpClient, runId: string): Promise<RunUnit>;
+export declare function listRunEvents(http: HttpClient, runId: string, options?: {
+    readonly channel?: "event" | "log" | "all";
+}): Promise<readonly RunEvent[]>;
+/** A coordinator WS connection grant minted by the hosted API's ticket broker. */
+export interface CoordinatorTicket {
+    readonly wsUrl: string;
+    readonly ticket: string;
+    readonly expiresAtMs: number;
+}
+/**
+ * Mint a short-lived coordinator WS ticket via the workspace-token-gated
+ * broker (`/api/runs/:id/events/ticket`). The returned `wsUrl` + `ticket`
+ * open the live event stream directly against the coordinator. Throws if no
+ * coordinator is configured for the deployment (HTTP 503).
+ */
+export declare function getCoordinatorTicket(http: HttpClient, runId: string): Promise<CoordinatorTicket>;
+export declare function listOutputs(http: HttpClient, runId: string): Promise<readonly Output[]>;
+/**
+ * List the run's platform diagnostics (the `logs` namespace). Legacy stored
+ * filenames are normalized to canonical public namespaces.
+ */
+export declare function listLogs(http: HttpClient, runId: string): Promise<readonly Output[]>;
+export declare function createOutputLink(http: HttpClient, runId: string, outputId: string): Promise<SignedOutputLink>;
+export declare function resolveOutputFileSelector(outputs: readonly Output[], selector: OutputFileSelector, runId?: string): Output;
+export declare function downloadOutput(http: HttpClient, runId: string, selector: OutputFileSelector): Promise<OutputFileDownload>;
+export declare function cancelRun(http: HttpClient, runId: string): Promise<void>;
+export declare function deleteRun(http: HttpClient, runId: string): Promise<void>;
+/**
+ * Delete a workspace asset cache entry. Accepts an `asset_<id>` value,
+ * `sha256:<hex>`, or a bare 64-hex digest. Workspace is derived server-side
+ * from the token; idempotent.
+ * Does NOT affect runs that already snapshotted the asset.
+ */
+export declare function deleteWorkspaceAsset(http: HttpClient, hash: string): Promise<void>;
+export declare function whoami(http: HttpClient): Promise<WhoAmI>;
+/**
+ * Download EVERYTHING about a run as one zip, organised into the four
+ * namespace folders:
+ *
+ *   metadata/run.json     — the run record.
+ *   events/events.jsonl   — typed event-channel records.
+ *   events/logs.jsonl     — log-channel records, when the API serves them.
+ *   events/all.jsonl      — full unified stream, when the API serves it.
+ *   outputs/<rel>         — the run's deliverables.
+ *   logs/<rel>            — platform diagnostics.
+ *   manifest.json         — `RunRecordManifestV1`.
+ */
+export declare function download(http: HttpClient, runId: string): Promise<Uint8Array>;
+/**
+ * Download only the run's deliverables (the `outputs` namespace). Zip
+ * layout: `<rel>` per file plus a `manifest.json`
+ * (`{ runId, namespace: "outputs", outputs[], errors[] }`).
+ */
+export declare function downloadOutputs(http: HttpClient, runId: string): Promise<Uint8Array>;
+/**
+ * Download only the platform diagnostics (the `logs` namespace). Zip
+ * layout: `<rel>` per file plus a `manifest.json`
+ * (`{ runId, namespace: "logs", logs[], errors[] }`).
+ */
+export declare function downloadLogs(http: HttpClient, runId: string): Promise<Uint8Array>;
+/**
+ * Download only the event archive (the `events` namespace). Always includes
+ * typed `events.jsonl`; includes `logs.jsonl` / `all.jsonl` when the deployed
+ * event API proves those channel exports are available.
+ */
+export declare function downloadEvents(http: HttpClient, runId: string): Promise<Uint8Array>;
+/**
+ * Download only the run record (the `metadata` namespace) as a zip
+ * containing `run.json`.
+ */
+export declare function downloadMetadata(http: HttpClient, runId: string): Promise<Uint8Array>;
+export declare function submitRun(http: HttpClient, request: PlatformRunSubmissionInput): Promise<Run>;
+/**
+ * Multipart variant of `submitRun` for runs that carry transient
+ * (per-run) skill bundles and/or transient AgentsMd content.
+ *
+ * The JSON submission travels as the `submission` part; each
+ * `InlineSkillRef.slot` in `request.submission.skills` MUST be
+ * mirrored by exactly one `skill:<slot>` part with the bundle bytes.
+ * Each `InlineAgentsMdRef.slot` in `request.submission.agentsMd`
+ * MUST be mirrored by exactly one `agentsmd:<slot>` part with the
+ * markdown text.
+ *
+ * The BFF re-canonicalises and re-hashes each bundle/file; a
+ * `contentHash` mismatch is rejected with a deterministic error.
+ *
+ * At least one of `bundles` or `agentsMdParts` must be non-empty.
+ */
+export declare function submitRunMultipart(http: HttpClient, request: PlatformRunSubmissionInput, bundles: ReadonlyArray<{
+    readonly slot: string;
+    readonly bytes: Uint8Array;
+    readonly filename: string;
+}>, agentsMdParts?: ReadonlyArray<{
+    readonly slot: string;
+    readonly content: string;
+    readonly filename: string;
+}>, fileParts?: ReadonlyArray<{
+    readonly slot: string;
+    readonly bytes: Uint8Array;
+    readonly filename: string;
+}>): Promise<Run>;
+/**
+ * Upload a workspace skill bundle as a zip blob. The hosted API runs
+ * the two-phase flow internally (insert pending row, stream bytes into
+ * object storage, validate manifest, transition to ready) and returns
+ * the finalized `Skill`. Use `Skill.fromPath` / `Skill.upload` in the
+ * SDK to build the body; this transport function only knows about
+ * bytes.
+ */
+export declare function createSkillBundle(http: HttpClient, args: {
+    readonly name: string;
+    readonly body: Blob | ArrayBuffer | Uint8Array;
+    readonly contentType?: string;
+    readonly filename?: string;
+}): Promise<Skill>;
+/**
+ * Upload a workspace skill bundle DIRECTLY to object storage via the presign
+ * flow, so the bytes never transit the hosted API (bundle size bounded by the
+ * object store, not API memory). Falls back to the buffered multipart
+ * `createSkillBundle` when the hosted API has no object-store upload
+ * credentials (503 `presign_unconfigured`).
+ *
+ *   1. POST /api/skills/presign     { name, hash, sizeBytes } → { uploadUrl, requiredHeaders, skillId }
+ *   2. PUT bytes → uploadUrl        (signed checksum; the store rejects a mismatch)
+ *   3. POST /api/skills/:id/finalize { manifest } → finalized Skill
+ *
+ * `manifest` is the client-computed bundle manifest (the caller already
+ * validated the zip shape before hashing); the Worker records it on finalize
+ * without re-buffering the object.
+ */
+export declare function createSkillBundleDirect(http: HttpClient, fetchImpl: (input: string, init?: RequestInit) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>, args: {
+    readonly name: string;
+    readonly body: Uint8Array;
+    readonly contentHash: string;
+    readonly manifest: ReadonlyArray<{
+        readonly path: string;
+        readonly size: number;
+        readonly mode?: number;
+    }>;
+    readonly contentType?: string;
+}): Promise<Skill>;
+export declare function listSkills(http: HttpClient): Promise<readonly Skill[]>;
+export declare function getSkill(http: HttpClient, skillId: string): Promise<Skill>;
+export declare function deleteSkill(http: HttpClient, 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.
+ *
+ * `contentHash` is the wire format `sha256:<hex>` as returned by
+ * `hashSkillBundle`. This powers `Skill.uploadIfChanged` — the SDK
+ * computes the hash locally and calls this function to skip the upload
+ * when the bytes already exist.
+ */
+export declare function findSkillByHash(http: HttpClient, args: {
+    readonly name: string;
+    readonly contentHash: string;
+}): Promise<Skill | 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 on the existing `/api/skills` endpoint — the
+ * indexed by-hash route is reserved for `uploadIfChanged`.
+ */
+export declare function findSkillByName(http: HttpClient, name: string): Promise<Skill | null>;
+/**
+ * Upload a workspace AgentsMd file as a markdown string. The BFF
+ * canonicalises the content into a deterministic zip with AGENTS.md at
+ * root and runs the two-phase pending → ready upload.
+ */
+export declare function createAgentsMd(http: HttpClient, args: {
+    readonly name: string;
+    readonly content: string;
+}): Promise<AgentsMdRecord>;
+export declare function listAgentsMd(http: HttpClient): Promise<readonly AgentsMdRecord[]>;
+export declare function getAgentsMd(http: HttpClient, agentsMdId: string): Promise<AgentsMdRecord>;
+export declare function deleteAgentsMd(http: HttpClient, agentsMdId: string): Promise<void>;
+/**
+ * Upload a workspace File as a zip bundle. The BFF canonicalises the
+ * content and runs the two-phase pending → ready upload.
+ */
+export declare function createFile(http: HttpClient, args: {
+    readonly name: string;
+    readonly bytes: Uint8Array;
+}): Promise<FileRecord>;
+export declare function listFiles(http: HttpClient): Promise<readonly FileRecord[]>;
+export declare function getFile(http: HttpClient, fileId: string): Promise<FileRecord>;
+export declare function deleteFile(http: HttpClient, fileId: string): Promise<void>;
+export interface AssetUploadResult {
+    readonly assetId: string;
+    readonly contentHash: string;
+    readonly sizeBytes: number;
+    readonly exists: boolean;
+}
+/**
+ * Upload bytes to the hosted API's content-addressable asset endpoint.
+ * Returns a storage-neutral asset id suitable for `kind:"asset"` refs in a
+ * later run submission.
+ */
+export declare function uploadWorkspaceAsset(http: HttpClient, input: {
+    readonly bytes: Uint8Array;
+    /** Optional `sha256:<hex>` advisory hash; the server verifies it. */
+    readonly contentHash?: string;
+    readonly contentType?: string;
+}): Promise<AssetUploadResult>;