@aithos/sdk 0.1.0-alpha.6 → 0.1.0-alpha.60

package/dist/src/compute.js

@@ -16,10 +16,18 @@
 //
 // MVP scope: single-shot invocation. Multi-turn agentic loops (with native
 // tool calling on the proxy) will land in a follow-up.
-import { buildSignedEnvelope } from "@aithos/protocol-client";
+import { buildSignedEnvelope, } from "@aithos/protocol-client";
 import { computeInvokeUrl, } from "./endpoints.js";
-import { ownerKeyPair } from "./internal/protocol-client-bridge.js";
+import { delegateKeyPair, ownerKeyPair, } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
+import { LocalPendingTranscribeTracker, TranscribeDraftStore, } from "./transcribe-resilience.js";
+import { runAgenticLoopLocal, } from "./agent-loop.js";
+import { selectAgentTools } from "./agent-tools.js";
+import { dispatchAgentToolLocal, } from "./agent-dispatch.js";
+import { EthosNamespace } from "./ethos.js";
+/** Default / hard cap on client-side loop iterations (mirrors the proxy). */
+const DEFAULT_LOCAL_MAX_ITERATIONS = 6;
+const HARD_LOCAL_MAX_ITERATIONS = 12;
 /**
  * `sdk.compute` namespace. Constructed once by the {@link AithosSDK}
  * constructor; reads the active owner from the supplied
@@ -28,47 +36,831 @@ import { AithosSDKError } from "./types.js";
  */
 export class ComputeNamespace {
     #deps;
+    // Lazily-created browser resilience helpers (see transcribe-resilience.ts).
+    // Created on first access only — the core invoke path never touches them.
+    #pendingTracker = null;
+    #draftStore = null;
     constructor(deps) {
         this.#deps = deps;
     }
+    #tracker() {
+        if (!this.#pendingTracker)
+            this.#pendingTracker = new LocalPendingTranscribeTracker();
+        return this.#pendingTracker;
+    }
+    #draft() {
+        if (!this.#draftStore)
+            this.#draftStore = new TranscribeDraftStore();
+        return this.#draftStore;
+    }
     /**
      * Invoke a Bedrock model through the compute proxy. See
      * {@link InvokeBedrockArgs} and {@link InvokeBedrockResult}.
      *
+     * Two signer paths are supported:
+     *
+     *   - **Owner**: when the caller is signed in as an owner, the
+     *     envelope is signed with the owner's `#public` sphere key and
+     *     no mandate is attached (the proxy resolves the mandate
+     *     server-side from `params.mandate_id`).
+     *   - **Delegate**: when the caller is delegate-only (mandate
+     *     imported via `auth.importMandate`), the envelope is signed
+     *     with the delegate's bound keypair and the full SignedMandate
+     *     is attached so the proxy can verify both signature and
+     *     authorisation in one pass. The mandate must carry the
+     *     `compute.invoke` scope and the proxy enforces its constraints
+     *     (caps, allowed models, …) at server-side.
+     *
+     * Owner takes precedence: if a session has BOTH an owner and a
+     * matching delegate session, we use the owner key (more flexible —
+     * the mandate is dereferenced via `mandate_id` and there's no
+     * lifetime cliff if the delegate seed has been wiped).
+     *
      * @throws {AithosSDKError} on protocol errors. The `code` field is one of
-     *   `sdk_no_owner`, `network`, `http`, `empty`, or any code returned by
-     *   the proxy (`quota_exceeded`, `mandate_revoked`, `insufficient_credits`,
-     *   …).
+     *   `sdk_no_signer`, `sdk_no_delegate_for_mandate`, `network`, `http`,
+     *   `empty`, or any code returned by the proxy (`quota_exceeded`,
+     *   `mandate_revoked`, `insufficient_credits`, …).
      */
     async invokeBedrock(args) {
-        const { auth, appDid, endpoints, fetch: fetchImpl } = this.#deps;
-        const owner = auth._getOwnerSigners();
-        if (!owner || owner.destroyed) {
-            throw new AithosSDKError("sdk_no_owner", "no owner signed in; sign in via auth.signIn / signUp / signInWithGoogle / signInWithRecovery first");
-        }
-        const publicKp = ownerKeyPair(owner, "public");
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            model: args.model,
+            messages: args.messages,
+            idempotency_key: idempotencyKey,
+        };
+        if (args.system !== undefined)
+            params.system = args.system;
+        if (args.maxTokens !== undefined)
+            params.max_tokens = args.maxTokens;
+        if (args.temperature !== undefined)
+            params.temperature = args.temperature;
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_invoke",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /**
+     * Run an agentic conversation: a multi-turn Bedrock tool-calling loop that
+     * runs server-side in a single POST and is billed once for the cumulative
+     * token usage. Tools come from the Aithos MCP (declared via `mcp`); the
+     * model reads private user data from the client-decrypted `workingSet`.
+     *
+     * The loop, tool dispatch, and billing all happen on the proxy — the SDK
+     * makes ONE signed request and gets the final answer. Same signer paths as
+     * {@link invokeBedrock} (owner direct or delegate-under-mandate).
+     *
+     * @throws {AithosSDKError} `sdk_no_signer`, `sdk_no_delegate_for_mandate`,
+     *   `network`, `http`, `empty`, or any proxy code (`quota_exceeded`,
+     *   `mandate_revoked`, `insufficient_credits`, …).
+     */
+    async runConversation(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
         const url = computeInvokeUrl(endpoints);
         const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
         const params = {
-            app_did: appDid,
-            mandate_id: args.mandateId,
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
             model: args.model,
             messages: args.messages,
             idempotency_key: idempotencyKey,
         };
+        if (args.system !== undefined)
+            params.system = args.system;
+        if (args.mcp !== undefined)
+            params.mcp = args.mcp;
+        if (args.workingSet !== undefined)
+            params.working_set = args.workingSet;
+        if (args.maxTokens !== undefined)
+            params.max_tokens = args.maxTokens;
+        if (args.maxIterations !== undefined)
+            params.max_iterations = args.maxIterations;
+        if (args.temperature !== undefined)
+            params.temperature = args.temperature;
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_converse",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /**
+     * Run ONE Bedrock turn with tool-calling through the proxy
+     * (`aithos.compute_invoke_turn`). Returns the raw content blocks — including
+     * any `tool_use` — so the caller can dispatch tools and loop. This is the
+     * per-turn primitive the CLIENT-SIDE agentic loop is built on; most callers
+     * want {@link runConversationLocal} instead, which drives the loop and
+     * dispatches Aithos tools locally.
+     *
+     * Same signer paths and billing as {@link invokeBedrock}; billed once per
+     * turn.
+     */
+    async invokeTurn(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            model: args.model,
+            messages: args.messages,
+            tools: args.tools,
+            idempotency_key: idempotencyKey,
+        };
+        if (args.system !== undefined)
+            params.system = args.system;
+        if (args.maxTokens !== undefined)
+            params.max_tokens = args.maxTokens;
+        if (args.temperature !== undefined)
+            params.temperature = args.temperature;
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_invoke_turn",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /**
+     * Run a CLIENT-SIDE agentic conversation with tool-calling: a multi-turn
+     * loop where each turn is one signed proxy call ({@link invokeTurn}) and the
+     * tools the model requests are dispatched LOCALLY against the user's own
+     * ethos (reads decrypt locally; writes stage + sign + publish locally). The
+     * proxy does pure per-turn inference and never holds a decryption key — keys,
+     * data, and dispatch all stay on the client (HANDOFF-AGENT-WRITE-MODE.md
+     * §1/§3).
+     *
+     * Authorisation: an owner has full authority over their own ethos; a
+     * delegate is bounded by the mandate's `ethos.read.*` / `ethos.write.*`
+     * scopes (a tool out of scope returns an error to the model — nothing is
+     * published). The spend capability (`compute.invoke`) is checked server-side
+     * on every turn.
+     *
+     * Billing is PER-TURN cumulative: each turn is billed once and the result's
+     * `creditsCharged` is the sum across turns.
+     *
+     * @throws {AithosSDKError} `sdk_no_signer`, `sdk_no_delegate_for_mandate`,
+     *   `network`, `http`, `empty`, or any proxy code. Tool-level failures do
+     *   NOT throw — they are fed back to the model as errors.
+     */
+    async runConversationLocal(args) {
+        // Resolve the subject whose ethos the agent operates on.
+        const subjectDid = this.#resolveSubjectDid(args.subjectDid, args.mandateId);
+        // Resolve the ethos client + the delegate scopes that bound writes.
+        const ethosNs = this.#ethosNamespace();
+        const ethosClient = await ethosNs.of(subjectDid);
+        const delegateScopes = ethosClient.mode === "delegate"
+            ? this.#delegateScopesForSubject(subjectDid)
+            : [];
+        const dispatchCtx = {
+            ethos: ethosClient,
+            delegateScopes,
+            ...(args.dataProvider ? { dataProvider: args.dataProvider } : {}),
+        };
+        const tools = selectAgentTools({
+            ...(args.tools ? { tools: args.tools } : {}),
+            ...(args.readOnly ? { readOnly: true } : {}),
+        });
+        const maxIterations = Math.max(1, Math.min(HARD_LOCAL_MAX_ITERATIONS, args.maxIterations ?? DEFAULT_LOCAL_MAX_ITERATIONS));
+        // Carry the last turn's billing metadata out of the loop.
+        let lastAuditId = "";
+        let lastFundedBy;
+        let lastReceiptId;
+        const initialMessages = args.messages.map((m) => ({
+            role: m.role,
+            content: m.content,
+        }));
+        const loop = await runAgenticLoopLocal({
+            messages: initialMessages,
+            maxIterations,
+            invokeTurn: async (messages) => {
+                const r = await this.invokeTurn({
+                    ...(args.mandateId !== undefined ? { mandateId: args.mandateId } : {}),
+                    model: args.model,
+                    messages,
+                    tools,
+                    ...(args.system !== undefined ? { system: args.system } : {}),
+                    ...(args.maxTokens !== undefined ? { maxTokens: args.maxTokens } : {}),
+                    ...(args.temperature !== undefined ? { temperature: args.temperature } : {}),
+                    ...(args.signal ? { signal: args.signal } : {}),
+                });
+                lastAuditId = r.auditId;
+                lastFundedBy = r.fundedBy;
+                lastReceiptId = r.receiptId;
+                return {
+                    content: r.content,
+                    stopReason: r.stopReason,
+                    usage: r.usage,
+                    creditsCharged: r.creditsCharged,
+                    walletBalance: r.walletBalance,
+                };
+            },
+            dispatch: (name, input) => dispatchAgentToolLocal(dispatchCtx, name, input),
+        });
+        return {
+            content: loop.finalContent,
+            stopReason: loop.stopReason,
+            iterations: loop.iterations,
+            usage: loop.usage,
+            toolCalls: loop.toolCalls,
+            creditsCharged: loop.creditsCharged,
+            walletBalance: loop.walletBalance,
+            auditId: lastAuditId,
+            ...(lastFundedBy ? { fundedBy: lastFundedBy } : {}),
+            ...(lastReceiptId ? { receiptId: lastReceiptId } : {}),
+        };
+    }
+    /**
+     * Multimodal Bedrock invoke — image + text → text response.
+     * Default model: `claude-sonnet-4-6` (vision-capable, reliable JSON).
+     *
+     * Use when you need a VLM to reason about an image: locating
+     * features, structured extraction, semantic Q&A. Prompt the model
+     * to return JSON if you need structured output (the API itself is
+     * unstructured).
+     */
+    async invokeBedrockVision(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        let imageBase64;
+        let imageContentType;
+        if ("base64" in args.image) {
+            imageBase64 = args.image.base64;
+            imageContentType = args.image.contentType;
+        }
+        else {
+            const buf = await args.image.arrayBuffer();
+            imageBase64 = arrayBufferToBase64(buf);
+            imageContentType = args.image.type || "image/png";
+        }
+        const url = computeInvokeUrl(endpoints);
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        const model = args.model ?? "claude-sonnet-4-6";
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            model,
+            image_base64: imageBase64,
+            image_content_type: imageContentType,
+            prompt: args.prompt,
+            idempotency_key: idempotencyKey,
+        };
         if (args.system !== undefined)
             params.system = args.system;
         if (args.maxTokens !== undefined)
             params.max_tokens = args.maxTokens;
         if (args.temperature !== undefined)
             params.temperature = args.temperature;
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_invoke_bedrock_vision",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /**
+     * Generate one or more images through the Aithos compute proxy
+     * (currently powered by fal.ai FLUX models). Spec mirror of
+     * {@link invokeBedrock}: same envelope, same wallet path, same
+     * mandate-scope gate (`compute.invoke` + `allowed_models`). The
+     * separation at the JSON-RPC method level (`aithos.compute_invoke_image`
+     * vs `aithos.compute_invoke`) commits each envelope to a specific
+     * modality so a stolen text-invoke envelope cannot be replayed
+     * against the image endpoint.
+     *
+     * Default model: `"image:flux-pro-1.1"`. Default aspect ratio: 1:1.
+     * Default count: 1 image.
+     *
+     * Pricing is per image and deterministic (no token-based reconcile):
+     *   - flux-schnell:        3 000 mc + fee per image
+     *   - flux-dev:           25 000 mc + fee per image
+     *   - flux-pro-1.1:       40 000 mc + fee per image
+     *   - flux-pro-1.1-ultra: 60 000 mc + fee per image
+     */
+    async invokeImage(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        // Default is Imagen 4 since alpha.17 — flat-illustration style is
+        // the right match for brand-mascot use cases. FLUX Pro 1.1 remains
+        // available via explicit `model: "image:flux-pro-1.1"`.
+        const model = args.model ?? "image:imagen-4";
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            model,
+            prompt: args.prompt,
+            idempotency_key: idempotencyKey,
+        };
+        if (args.negativePrompt !== undefined)
+            params.negative_prompt = args.negativePrompt;
+        if (args.aspectRatio !== undefined)
+            params.aspect_ratio = args.aspectRatio;
+        if (args.seed !== undefined)
+            params.seed = args.seed;
+        if (args.numberOfImages !== undefined)
+            params.number_of_images = args.numberOfImages;
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_invoke_image",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /**
+     * Run text-prompted segmentation (Florence-2 referring-expression)
+     * on a source image. Returns one or more polygons hugging the
+     * region matching the text prompt.
+     *
+     * Use cases: locate the chest/torso area of a generated mascot
+     * for logo compositing, find the face zone for a thumbnail crop,
+     * extract a product from a marketing shot — anything that needs
+     * a precise mask + bbox from natural-language description.
+     *
+     * Pricing: flat 5 000 mc per call (~$0.005 — Florence-2 is cheap).
+     */
+    async invokeSegmentation(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        // Normalize image input to base64 + content type.
+        let imageBase64;
+        let imageContentType;
+        if ("base64" in args.image) {
+            imageBase64 = args.image.base64;
+            imageContentType = args.image.contentType;
+        }
+        else {
+            const buf = await args.image.arrayBuffer();
+            imageBase64 = arrayBufferToBase64(buf);
+            imageContentType = args.image.type || "image/png";
+        }
+        const url = computeInvokeUrl(endpoints);
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            image_base64: imageBase64,
+            image_content_type: imageContentType,
+            text_input: args.textInput,
+            idempotency_key: idempotencyKey,
+        };
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_invoke_segmentation",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /* ---------------------------------------------------------------------- */
+    /*  Transcription — low-level (advanced) API                              */
+    /*                                                                        */
+    /*  Four thin wrappers over the JSON-RPC methods. Use these when you want */
+    /*  to own the upload + polling loop; otherwise prefer `invokeTranscribe` */
+    /*  which composes them. All four are isomorphic (sign + POST only).      */
+    /* ---------------------------------------------------------------------- */
+    /**
+     * Provision a transcription job and get a pre-signed S3 URL to PUT the
+     * audio to. No wallet debit. `mandateId` only selects the delegate
+     * signer (it is not part of the wire params for prepare).
+     */
+    async prepareTranscribe(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const params = {
+            app_did: this.#deps.appDid,
+            content_type: args.contentType,
+        };
+        if (args.durationSecEstimate !== undefined) {
+            params.duration_sec_estimate = args.durationSecEstimate;
+        }
+        const r = await this.#signAndPost({
+            url,
+            method: "aithos.compute_transcribe_prepare",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+        return {
+            jobId: r.job_id,
+            uploadUrl: r.upload_url,
+            s3ObjectKey: r.s3_object_key,
+            expiresAt: r.expires_at,
+        };
+    }
+    /**
+     * Verify the uploaded audio, pre-debit the wallet, and launch the AWS
+     * Transcribe job. Returns immediately with `status: "running"`.
+     */
+    async startTranscribe(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            job_id: args.jobId,
+            model: args.model,
+            duration_sec: args.durationSec,
+        };
+        if (args.languageCode !== undefined)
+            params.language_code = args.languageCode;
+        if (args.diarization !== undefined)
+            params.diarization = args.diarization;
+        if (args.idempotencyKey !== undefined)
+            params.idempotency_key = args.idempotencyKey;
+        const r = await this.#signAndPost({
+            url,
+            method: "aithos.compute_transcribe_start",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+        return {
+            jobId: r.job_id,
+            status: "running",
+            estimatedCredits: r.estimated_credits,
+            walletBalance: r.walletBalance,
+            ...(r.fundedBy ? { fundedBy: r.fundedBy } : {}),
+            ...(r.receiptId ? { receiptId: r.receiptId } : {}),
+        };
+    }
+    /**
+     * Poll a job's status. On completion the server finalises (reconcile +
+     * audit) and returns the transcript; a resumed poll after reconnect
+     * re-reads the transcript while it's still in the 24h output window.
+     */
+    async getTranscribeStatus(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const params = { job_id: args.jobId };
+        const r = await this.#signAndPost({
+            url,
+            method: "aithos.compute_transcribe_status",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+        return mapTranscribeStatus(args.jobId, r);
+    }
+    /**
+     * List the caller's transcription jobs. Excludes terminal `completed`
+     * jobs unless `includeCompleted` is set — the resilience "what's still
+     * pending server-side" query.
+     */
+    async listPendingTranscribes(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args?.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const params = {};
+        if (args?.includeCompleted !== undefined) {
+            params.include_completed = args.includeCompleted;
+        }
+        const r = await this.#signAndPost({
+            url,
+            method: "aithos.compute_transcribe_list_pending",
+            params,
+            choice,
+            fetchImpl,
+            signal: args?.signal,
+        });
+        return {
+            jobs: (r.jobs ?? []).map((j) => ({
+                jobId: String(j.job_id),
+                status: j.status,
+                createdAt: Number(j.created_at),
+                ...(j.estimated_credits !== undefined
+                    ? { estimatedCredits: Number(j.estimated_credits) }
+                    : {}),
+                ...(j.creditsCharged !== undefined
+                    ? { creditsCharged: Number(j.creditsCharged) }
+                    : {}),
+            })),
+        };
+    }
+    /* ---------------------------------------------------------------------- */
+    /*  Transcription — high-level one-call API                               */
+    /* ---------------------------------------------------------------------- */
+    /**
+     * Transcribe an audio Blob to text in one call. Composes the four
+     * low-level methods: prepare → direct S3 upload → start → poll. Returns
+     * the transcript and stores NOTHING server-side beyond the ephemeral
+     * job — the consumer decides what to do with the result.
+     *
+     * Isomorphic: depends only on `Blob`, `fetch`/`XMLHttpRequest` and
+     * timers. On a backend, pass `durationSecOverride` (no Blob duration
+     * probing is possible without a DOM); in a browser the duration is
+     * probed automatically when omitted.
+     *
+     * Resilience: the job id is recorded in a localStorage tracker (browser)
+     * before upload, so `listLocalPendingTranscribes()` / `resumeTranscribe()`
+     * can recover a job whose result never arrived. In Node the tracker is a
+     * harmless in-memory no-op.
+     */
+    async invokeTranscribe(args) {
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        const model = args.model ?? "transcribe:aws-fr-standard";
+        const contentType = args.audio.type || "audio/webm";
+        const durationSec = args.durationSecOverride ?? (await probeBlobDuration(args.audio));
+        args.onProgress?.({ phase: "queued" });
+        // 1. Prepare — pre-signed S3 URL + job id.
+        const prepared = await this.prepareTranscribe({
+            contentType,
+            durationSecEstimate: durationSec,
+            ...(args.mandateId ? { mandateId: args.mandateId } : {}),
+            ...(args.signal ? { signal: args.signal } : {}),
+        });
+        const tracker = this.#tracker();
+        tracker.upsert(prepared.jobId, "uploading", { model, contentType });
+        // 2. Upload the blob straight to S3 (the proxy never sees the bytes).
+        try {
+            await uploadToS3WithProgress(prepared.uploadUrl, args.audio, contentType, {
+                onProgress: (b, t) => args.onProgress?.({ phase: "uploading", bytesUploaded: b, totalBytes: t }),
+                signal: args.signal,
+                fetchImpl: this.#deps.fetch,
+            });
+        }
+        catch (e) {
+            tracker.upsert(prepared.jobId, "failed");
+            throw e instanceof AithosSDKError
+                ? e
+                : new AithosSDKError("transcribe_upload_failed", e.message);
+        }
+        // 3. Start — pre-debit + launch AWS Transcribe.
+        args.onProgress?.({ phase: "starting" });
+        await this.startTranscribe({
+            jobId: prepared.jobId,
+            ...(args.mandateId ? { mandateId: args.mandateId } : {}),
+            model,
+            durationSec,
+            ...(args.languageCode ? { languageCode: args.languageCode } : {}),
+            ...(args.diarization !== undefined ? { diarization: args.diarization } : {}),
+            idempotencyKey,
+            ...(args.signal ? { signal: args.signal } : {}),
+        });
+        tracker.upsert(prepared.jobId, "running");
+        // 4. Poll to completion.
+        const result = await this.#pollUntilTerminal(prepared.jobId, {
+            ...(args.mandateId ? { mandateId: args.mandateId } : {}),
+            ...(args.signal ? { signal: args.signal } : {}),
+            ...(args.onProgress ? { onProgress: args.onProgress } : {}),
+            ...(args.pollIntervalMs ? { pollIntervalMs: args.pollIntervalMs } : {}),
+        });
+        tracker.remove(prepared.jobId);
+        return result;
+    }
+    /**
+     * Resume polling an in-flight job by id — for recovery after a reload or
+     * crash. Returns the final result and clears the job from the local
+     * pending tracker. Throws if the job has already failed.
+     */
+    async resumeTranscribe(jobId, opts) {
+        const result = await this.#pollUntilTerminal(jobId, {
+            ...(opts?.mandateId ? { mandateId: opts.mandateId } : {}),
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+            ...(opts?.onProgress ? { onProgress: opts.onProgress } : {}),
+            ...(opts?.pollIntervalMs ? { pollIntervalMs: opts.pollIntervalMs } : {}),
+        });
+        this.#tracker().remove(jobId);
+        return result;
+    }
+    async #pollUntilTerminal(jobId, opts) {
+        const startedAt = Date.now();
+        let backoffMs = opts.pollIntervalMs ?? 2000;
+        for (;;) {
+            if (opts.signal?.aborted) {
+                throw new AithosSDKError("aborted", "transcription aborted");
+            }
+            const st = await this.getTranscribeStatus({
+                jobId,
+                ...(opts.mandateId ? { mandateId: opts.mandateId } : {}),
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            });
+            if (st.status === "completed") {
+                opts.onProgress?.({ phase: "completed" });
+                return {
+                    text: st.text,
+                    segments: st.segments,
+                    words: st.words,
+                    durationSec: st.durationSec,
+                    languageCode: st.languageCode,
+                    creditsCharged: st.creditsCharged,
+                    walletBalance: st.walletBalance,
+                    auditId: st.auditId,
+                    jobId: st.jobId,
+                    ...(st.fundedBy ? { fundedBy: st.fundedBy } : {}),
+                    ...(st.sponsoredBy ? { sponsoredBy: st.sponsoredBy } : {}),
+                    ...(st.receiptId ? { receiptId: st.receiptId } : {}),
+                };
+            }
+            if (st.status === "failed") {
+                this.#tracker().upsert(jobId, "failed");
+                throw new AithosSDKError(st.error.code || "transcribe_failed", st.error.message);
+            }
+            opts.onProgress?.({
+                phase: "processing",
+                elapsedSec: Math.floor((Date.now() - startedAt) / 1000),
+            });
+            await sleep(backoffMs, opts.signal);
+            backoffMs = Math.min(15_000, Math.ceil(backoffMs * 1.5));
+        }
+    }
+    /* ---------------------------------------------------------------------- */
+    /*  Transcription — browser resilience (framework-agnostic)               */
+    /* ---------------------------------------------------------------------- */
+    /** Snapshot of locally-tracked in-flight jobs (stable ref between mutations). */
+    listLocalPendingTranscribes() {
+        return this.#tracker().list();
+    }
+    /** Stable snapshot for `useSyncExternalStore`-style consumers. */
+    getLocalPendingTranscribesSnapshot() {
+        return this.#tracker().getSnapshot();
+    }
+    /**
+     * Subscribe to changes in the local pending-jobs registry. Returns an
+     * unsubscribe function. Framework-agnostic: wrap it in a React
+     * `useSyncExternalStore`, a Vue effect, a Svelte store, etc.
+     */
+    subscribeLocalPendingTranscribes(listener) {
+        return this.#tracker().subscribe(listener);
+    }
+    /**
+     * IndexedDB-backed draft queue: persist a recording before any network
+     * call, upload it when the user confirms. Browser-only (methods reject
+     * with TranscribeDraftUnavailableError when IndexedDB is absent).
+     */
+    get transcribeDraft() {
+        const store = this.#draft();
+        const self = this;
+        return {
+            save: (blob, meta) => store.save(blob, meta),
+            list: () => store.list(),
+            get: (draftId) => store.get(draftId),
+            delete: (draftId) => store.delete(draftId),
+            upload: async (draftId, args) => {
+                const rec = await store.get(draftId);
+                if (!rec) {
+                    throw new AithosSDKError("draft_not_found", `no transcription draft '${draftId}'`);
+                }
+                const result = await self.invokeTranscribe({ ...args, audio: rec.blob });
+                await store.delete(draftId);
+                return result;
+            },
+        };
+    }
+    /**
+     * Lazily-built EthosNamespace for the local agent dispatch — reuses the
+     * compute deps (auth / endpoints / fetch), so no extra wiring in sdk.ts.
+     */
+    #ethosNs = null;
+    #ethosNamespace() {
+        if (!this.#ethosNs) {
+            this.#ethosNs = new EthosNamespace({
+                auth: this.#deps.auth,
+                endpoints: this.#deps.endpoints,
+                fetch: this.#deps.fetch,
+            });
+        }
+        return this.#ethosNs;
+    }
+    /**
+     * Resolve the subject DID the local agent operates on:
+     *   1. explicit `subjectDid` always wins;
+     *   2. else the signed-in owner;
+     *   3. else (delegate session) the subject of the imported mandate.
+     */
+    #resolveSubjectDid(explicit, mandateId) {
+        if (explicit && explicit.length > 0)
+            return explicit;
+        const owner = this.#deps.auth._getOwnerSigners();
+        if (owner && !owner.destroyed)
+            return owner.did;
+        if (mandateId) {
+            const actor = this.#deps.auth._getDelegateActor(mandateId);
+            if (actor && !actor.destroyed)
+                return actor.subjectDid;
+        }
+        throw new AithosSDKError("sdk_no_signer", "cannot determine the subject DID: sign in as an owner, pass a mandateId for a delegate session, or pass subjectDid explicitly.");
+    }
+    /** Scopes carried by the delegate mandate for `did` (empty if none). */
+    #delegateScopesForSubject(did) {
+        const actor = this.#deps.auth._findDelegateForSubject(did);
+        const raw = actor?.mandate?.scopes;
+        return Array.isArray(raw) ? raw.filter((s) => typeof s === "string") : [];
+    }
+    /**
+     * Resolve the active signer (owner takes precedence over delegate).
+     *
+     * - When an owner is signed in: returns the owner-signer regardless
+     *   of `mandateId` (the proxy ignores params.mandate_id on
+     *   owner-signed envelopes, so owners can omit it).
+     * - When delegate-only: requires `mandateId` to find the matching
+     *   imported bundle. Throws `sdk_no_delegate_for_mandate` if absent
+     *   or no match.
+     */
+    #resolveSigner(mandateId) {
+        const { auth } = this.#deps;
+        const owner = auth._getOwnerSigners();
+        const ownerLoaded = owner !== null && !owner.destroyed;
+        if (ownerLoaded) {
+            const publicKp = ownerKeyPair(owner, "public");
+            return {
+                kind: "owner",
+                iss: owner.did,
+                verificationMethod: `${owner.did}#public`,
+                signer: publicKp,
+                mandate: undefined,
+            };
+        }
+        if (mandateId === undefined || mandateId.length === 0) {
+            throw new AithosSDKError("sdk_no_signer", "no owner signed in and no mandateId provided — pass a mandateId for a delegate session, or sign in as an owner first.");
+        }
+        const actor = auth._getDelegateActor(mandateId);
+        if (!actor || actor.destroyed) {
+            throw new AithosSDKError("sdk_no_delegate_for_mandate", `no owner signed in and no imported delegate mandate matches '${mandateId}'. Sign in as an owner, or import a delegate bundle for that mandate via auth.importMandate.`);
+        }
+        const kp = delegateKeyPair(actor);
+        return {
+            kind: "delegate",
+            iss: actor.subjectDid,
+            verificationMethod: actor.granteePubkeyMultibase,
+            signer: kp,
+            // The DelegateActor stores the SignedMandate as a structurally
+            // opaque object so the SDK doesn't have to import the
+            // protocol-client type at the storage boundary. Round-trip
+            // through `unknown` for the TS cast — at runtime the bytes are
+            // the canonical SignedMandate the bundle parser already
+            // validated.
+            mandate: actor.mandate,
+        };
+    }
+    /**
+     * Resolve the `mandate_id` value the SDK writes into the JSON-RPC
+     * params for the wire. The proxy requires this field to be a
+     * non-empty string but only consults it for the delegate path —
+     * for owner-signed envelopes it's audit-log metadata, with no
+     * security implication.
+     *
+     * Strategy:
+     *   - Caller-provided id always wins (owner who wants to attribute
+     *     to a specific minted mandate can still pass it).
+     *   - Delegate path: the choice carries the real mandate.id — use it
+     *     so a delegate cannot accidentally lie about which mandate
+     *     it claims to spend under.
+     *   - Owner path with no explicit id: use the owner DID followed
+     *     by `#self` — a stable sentinel that's unambiguously not a
+     *     real mandate id (mandate ids are ULIDs).
+     */
+    #resolveMandateIdForWire(explicit, choice) {
+        if (explicit && explicit.length > 0)
+            return explicit;
+        if (choice.kind === "delegate")
+            return choice.mandate.id;
+        // Owner-direct sentinel. The proxy never inspects this value
+        // beyond non-empty-string validation when no mandate is attached.
+        return `${choice.iss}#self`;
+    }
+    /**
+     * Sign the params with the resolved signer and POST a JSON-RPC
+     * request. Shared between `invokeBedrock` and `invokeImage` — the
+     * only difference between those two is the method name and the
+     * params shape; the envelope construction + transport + error
+     * mapping is identical.
+     */
+    async #signAndPost(opts) {
+        const { url, method, params, choice, fetchImpl, signal } = opts;
         const envelope = buildSignedEnvelope({
-            iss: owner.did,
+            iss: choice.iss,
             aud: url,
-            method: "aithos.compute_invoke",
-            verificationMethod: `${owner.did}#public`,
+            method,
+            verificationMethod: choice.verificationMethod,
             params,
-            signer: publicKp,
+            signer: choice.signer,
+            ...(choice.kind === "delegate" ? { mandate: choice.mandate } : {}),
         });
         let res;
         try {
@@ -77,11 +869,11 @@ export class ComputeNamespace {
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify({
                     jsonrpc: "2.0",
-                    id: "aithos.compute_invoke",
-                    method: "aithos.compute_invoke",
+                    id: method,
+                    method,
                     params: { ...params, _envelope: envelope },
                 }),
-                ...(args.signal ? { signal: args.signal } : {}),
+                ...(signal ? { signal } : {}),
             });
         }
         catch (e) {
@@ -109,4 +901,160 @@ function generateIdempotencyKey() {
     }
     return hex;
 }
+/**
+ * Probe an audio Blob's duration (seconds) in a browser. Returns 0 when no
+ * DOM is available (Node / SSR) or probing fails — the caller should pass
+ * `durationSecOverride` on a backend. Never throws.
+ */
+async function probeBlobDuration(blob) {
+    try {
+        if (typeof document === "undefined" ||
+            typeof URL === "undefined" ||
+            typeof Audio === "undefined") {
+            return 0;
+        }
+        return await new Promise((resolve) => {
+            const url = URL.createObjectURL(blob);
+            const audio = new Audio();
+            let settled = false;
+            const done = (v) => {
+                if (settled)
+                    return;
+                settled = true;
+                try {
+                    URL.revokeObjectURL(url);
+                }
+                catch {
+                    /* ignore */
+                }
+                resolve(Number.isFinite(v) && v > 0 ? v : 0);
+            };
+            audio.preload = "metadata";
+            audio.onloadedmetadata = () => done(audio.duration);
+            audio.onerror = () => done(0);
+            audio.src = url;
+            setTimeout(() => done(0), 5000);
+        });
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * PUT a Blob to a pre-signed S3 URL. Uses XMLHttpRequest in browsers for
+ * real upload-progress events; falls back to `fetch` on Node (coarse
+ * 0→100% progress). Honors an AbortSignal.
+ */
+async function uploadToS3WithProgress(url, blob, contentType, opts) {
+    const total = blob.size;
+    if (typeof XMLHttpRequest !== "undefined") {
+        await new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("PUT", url, true);
+            xhr.setRequestHeader("Content-Type", contentType);
+            xhr.upload.onprogress = (e) => {
+                if (e.lengthComputable)
+                    opts.onProgress?.(e.loaded, e.total);
+            };
+            xhr.onload = () => {
+                if (xhr.status >= 200 && xhr.status < 300)
+                    resolve();
+                else
+                    reject(new AithosSDKError("transcribe_upload_failed", `S3 upload failed: HTTP ${xhr.status}`));
+            };
+            xhr.onerror = () => reject(new AithosSDKError("transcribe_upload_failed", "S3 upload network error"));
+            xhr.onabort = () => reject(new AithosSDKError("aborted", "S3 upload aborted"));
+            if (opts.signal) {
+                if (opts.signal.aborted) {
+                    xhr.abort();
+                    return;
+                }
+                opts.signal.addEventListener("abort", () => xhr.abort(), { once: true });
+            }
+            xhr.send(blob);
+        });
+        return;
+    }
+    // Node / no XHR — use the injected fetch (falls back to global fetch).
+    opts.onProgress?.(0, total);
+    const doFetch = opts.fetchImpl ?? fetch;
+    const res = await doFetch(url, {
+        method: "PUT",
+        headers: { "content-type": contentType },
+        body: blob,
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    if (!res.ok) {
+        throw new AithosSDKError("transcribe_upload_failed", `S3 upload failed: HTTP ${res.status}`);
+    }
+    opts.onProgress?.(total, total);
+}
+/** Sleep `ms`, rejecting early if the signal aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, ms);
+        if (signal) {
+            if (signal.aborted) {
+                clearTimeout(t);
+                reject(new AithosSDKError("aborted", "aborted"));
+                return;
+            }
+            signal.addEventListener("abort", () => {
+                clearTimeout(t);
+                reject(new AithosSDKError("aborted", "aborted"));
+            }, { once: true });
+        }
+    });
+}
+/** Coerce a raw `transcribe_status` JSON-RPC result into the typed union. */
+function mapTranscribeStatus(jobId, r) {
+    const status = r.status;
+    if (status === "completed") {
+        const fundedBy = r.fundedBy;
+        return {
+            jobId,
+            status: "completed",
+            text: String(r.text ?? ""),
+            segments: r.segments ?? [],
+            words: r.words ?? [],
+            durationSec: Number(r.duration_sec_actual ?? 0),
+            languageCode: String(r.language_code ?? ""),
+            creditsCharged: Number(r.creditsCharged ?? 0),
+            walletBalance: Number(r.walletBalance ?? 0),
+            auditId: String(r.auditId ?? ""),
+            ...(fundedBy === "sponsored" || fundedBy === "grant" || fundedBy === "purchase"
+                ? { fundedBy }
+                : {}),
+            ...(typeof r.sponsoredBy === "string" ? { sponsoredBy: r.sponsoredBy } : {}),
+            ...(typeof r.receiptId === "string" ? { receiptId: r.receiptId } : {}),
+        };
+    }
+    if (status === "failed") {
+        const err = r.error ?? {};
+        return {
+            jobId,
+            status: "failed",
+            error: {
+                code: String(err.code ?? "transcribe_failed"),
+                message: String(err.message ?? ""),
+            },
+        };
+    }
+    return { jobId, status: "running", elapsedSec: Number(r.elapsed_sec ?? 0) };
+}
+/**
+ * Encode an ArrayBuffer as base64 in environments where `Buffer` is
+ * not available (browser). Uses btoa over a binary string — safe for
+ * the small payload sizes the SDK deals with (≤ a few MB).
+ */
+function arrayBufferToBase64(buf) {
+    const bytes = new Uint8Array(buf);
+    let bin = "";
+    // Process in chunks to avoid stack overflow on String.fromCharCode.apply
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        bin += String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + CHUNK)));
+    }
+    return btoa(bin);
+}
 //# sourceMappingURL=compute.js.map