@aithos/sdk 0.1.0-alpha.53 → 0.1.0-alpha.54

package/dist/src/compute.d.ts

@@ -90,6 +90,89 @@ export interface InvokeBedrockResult {
      */
     readonly sponsoredRemainingForUser?: number;
 }
+/** A decrypted ethos section in the working-set. */
+export interface WorkingSetSection {
+    readonly id: string;
+    readonly title: string;
+    readonly body: string;
+}
+/**
+ * Client-decrypted data the agentic loop may read server-side. Built in the
+ * browser (where the keys live) from exactly the zones / collections the
+ * mandate grants — the proxy never holds a standing decryption key
+ * (see PLATFORM-COMPUTE-AGENTIC-MCP.md §4). Use {@link ComputeNamespace}
+ * with a `mcp` reference + this working-set.
+ */
+export interface ComputeWorkingSet {
+    /** Decrypted ethos sections, per zone. Only granted zones appear. */
+    readonly ethos?: {
+        readonly public?: readonly WorkingSetSection[];
+        readonly circle?: readonly WorkingSetSection[];
+        readonly self?: readonly WorkingSetSection[];
+    };
+    /** Decrypted structured data, per collection name. */
+    readonly data?: Record<string, readonly Record<string, unknown>[]>;
+}
+/** A tool invocation the loop performed (trace for UI / debugging). */
+export interface ConverseToolCall {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly turn: number;
+}
+export type ConverseStopReason = "end_turn" | "max_tokens" | "stop_sequence" | "max_iterations" | "budget_exhausted";
+export interface RunConversationArgs {
+    /** Mandate id — optional for owner sessions, required for delegate sessions. */
+    readonly mandateId?: string;
+    /** Claude model id (text or vision). */
+    readonly model: string;
+    /** Initial conversation. The loop's internal tool turns are server-side. */
+    readonly messages: readonly ComputeMessage[];
+    /** Optional system prompt. */
+    readonly system?: string;
+    /**
+     * MCP tools to expose to the model. v1 only supports the Aithos server.
+     * Omit `tools` to expose the full Aithos catalogue; pass a subset to narrow.
+     */
+    readonly mcp?: {
+        readonly server: "aithos";
+        readonly tools?: readonly string[];
+    };
+    /**
+     * Client-decrypted working-set the tools read from. Build it with
+     * {@link ComputeNamespace.buildWorkingSet}. Required for any tool that
+     * touches private (circle/self) or structured data.
+     */
+    readonly workingSet?: ComputeWorkingSet;
+    /** Cap on Bedrock turns. Server clamps to its own hard cap. Default 6. */
+    readonly maxIterations?: number;
+    /** Per-turn output token cap. */
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    /** Idempotency key for the WHOLE conversation (generated if omitted). */
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface RunConversationResult {
+    /** Final assistant text. */
+    readonly content: string;
+    readonly stopReason: ConverseStopReason;
+    /** Number of Bedrock turns performed (each was a billed call). */
+    readonly iterations: number;
+    /** Token usage summed over all turns. */
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+    /** Trace of the tool calls the loop made. */
+    readonly toolCalls: readonly ConverseToolCall[];
+    /** Total microcredits debited for the whole conversation. */
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+    readonly fundedBy?: "sponsored" | "grant" | "purchase";
+    readonly receiptId?: string;
+    readonly sponsoredBy?: string;
+}
 /**
  * Stable cross-provider image model ids supported by the Aithos compute
  * proxy. New models can be added on the server side without an SDK
@@ -399,6 +482,21 @@ export declare class ComputeNamespace {
      *   `mandate_revoked`, `insufficient_credits`, …).
      */
     invokeBedrock(args: InvokeBedrockArgs): Promise<InvokeBedrockResult>;
+    /**
+     * 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`, …).
+     */
+    runConversation(args: RunConversationArgs): Promise<RunConversationResult>;
     /**
      * Multimodal Bedrock invoke — image + text → text response.
      * Default model: `claude-sonnet-4-6` (vision-capable, reliable JSON).

package/dist/src/compute.js

@@ -101,6 +101,53 @@ export class ComputeNamespace {
             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: 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,
+        });
+    }
     /**
      * Multimodal Bedrock invoke — image + text → text response.
      * Default model: `claude-sonnet-4-6` (vision-capable, reliable JSON).

package/dist/src/index.d.ts

@@ -5,7 +5,7 @@ export { AithosSDKError } from "./types.js";
 export { AithosRpcError } from "@aithos/protocol-client";
 export type { AithosSdkEndpoints } from "./endpoints.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
-export type { ComputeMessage, ImageAspectRatio, ImageModelId, InvokeBedrockArgs, InvokeBedrockResult, InvokeBedrockVisionArgs, InvokeBedrockVisionResult, InvokeImageArgs, InvokeImageImage, InvokeImageResult, InvokeSegmentationArgs, InvokeSegmentationResult, SegmentPolygon, StopReason, TranscribeModelId, TranscribeProgressState, TranscribeSegment, TranscribeWord, InvokeTranscribeArgs, InvokeTranscribeResult, PrepareTranscribeArgs, PrepareTranscribeResult, StartTranscribeArgs, StartTranscribeResult, TranscribeStatusResult, TranscribeJobSummary, } from "./compute.js";
+export type { ComputeMessage, ImageAspectRatio, ImageModelId, InvokeBedrockArgs, InvokeBedrockResult, InvokeBedrockVisionArgs, InvokeBedrockVisionResult, InvokeImageArgs, InvokeImageImage, InvokeImageResult, InvokeSegmentationArgs, InvokeSegmentationResult, SegmentPolygon, StopReason, RunConversationArgs, RunConversationResult, ComputeWorkingSet, WorkingSetSection, ConverseToolCall, ConverseStopReason, TranscribeModelId, TranscribeProgressState, TranscribeSegment, TranscribeWord, InvokeTranscribeArgs, InvokeTranscribeResult, PrepareTranscribeArgs, PrepareTranscribeResult, StartTranscribeArgs, StartTranscribeResult, TranscribeStatusResult, TranscribeJobSummary, } from "./compute.js";
 export { ComputeNamespace } from "./compute.js";
 export type { LocalPendingEntry, LocalPendingStatus, TranscribeDraftMeta, TranscribeDraftRecord, } from "./transcribe-resilience.js";
 export { LocalPendingTranscribeTracker, TranscribeDraftStore, TranscribeDraftUnavailableError, } from "./transcribe-resilience.js";

package/dist/src/sdk.d.ts

@@ -1,8 +1,8 @@
 import type { AithosAuth } from "./auth.js";
 import { AppsNamespace } from "./apps.js";
-import { ComputeNamespace } from "./compute.js";
+import { ComputeNamespace, type ComputeWorkingSet } from "./compute.js";
 import { type AithosSdkEndpoints } from "./endpoints.js";
-import { EthosNamespace } from "./ethos.js";
+import { EthosNamespace, type ZoneName } from "./ethos.js";
 import { MandatesNamespace } from "./mandates.js";
 import { WalletNamespace } from "./wallet.js";
 import { WebNamespace } from "./web.js";
@@ -57,5 +57,29 @@ export declare class AithosSDK {
     constructor(config: AithosSDKConfig);
     /** DID of the currently signed-in owner, or null if no owner is loaded. */
     get userDid(): string | null;
+    /**
+     * Build the client-decrypted working-set for an agentic conversation.
+     *
+     * Reads the requested ethos zones for `did` through {@link EthosNamespace}
+     * (which decrypts client-side using the active owner/delegate keys) and
+     * packages them into the {@link ComputeWorkingSet} shape that
+     * `sdk.compute.runConversation({ workingSet })` consumes.
+     *
+     * Only zones the session can actually read are included: a zone the
+     * mandate does not grant (or whose delegate wrap is missing) throws
+     * `ethos_zone_unreadable` / `ethos_anonymous_private_zone` on read and is
+     * silently skipped — so the working-set is naturally bounded by what the
+     * caller is authorized to see. The proxy never holds a decryption key;
+     * this is where the plaintext is produced (see PLATFORM-COMPUTE-AGENTIC-MCP.md §4).
+     *
+     * Structured (gamma) data collections are not loaded here in v1 — attach
+     * them to the returned object's `data` field yourself if needed.
+     *
+     * @param did     Subject DID whose ethos to read (usually the signed-in owner).
+     * @param opts.zones  Zones to attempt. Defaults to all three.
+     */
+    buildWorkingSet(did: string, opts?: {
+        readonly zones?: readonly ZoneName[];
+    }): Promise<ComputeWorkingSet>;
 }
 //# sourceMappingURL=sdk.d.ts.map

package/dist/src/sdk.js

@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Mathieu Colla
 import { AppsNamespace } from "./apps.js";
-import { ComputeNamespace } from "./compute.js";
+import { ComputeNamespace, } from "./compute.js";
 import { resolveEndpoints } from "./endpoints.js";
 import { EthosNamespace } from "./ethos.js";
 import { MandatesNamespace } from "./mandates.js";
+import { AithosSDKError } from "./types.js";
 import { WalletNamespace } from "./wallet.js";
 import { WebNamespace } from "./web.js";
 export class AithosSDK {
@@ -80,5 +81,48 @@ export class AithosSDK {
     get userDid() {
         return this.auth.getOwnerInfo()?.did ?? null;
     }
+    /**
+     * Build the client-decrypted working-set for an agentic conversation.
+     *
+     * Reads the requested ethos zones for `did` through {@link EthosNamespace}
+     * (which decrypts client-side using the active owner/delegate keys) and
+     * packages them into the {@link ComputeWorkingSet} shape that
+     * `sdk.compute.runConversation({ workingSet })` consumes.
+     *
+     * Only zones the session can actually read are included: a zone the
+     * mandate does not grant (or whose delegate wrap is missing) throws
+     * `ethos_zone_unreadable` / `ethos_anonymous_private_zone` on read and is
+     * silently skipped — so the working-set is naturally bounded by what the
+     * caller is authorized to see. The proxy never holds a decryption key;
+     * this is where the plaintext is produced (see PLATFORM-COMPUTE-AGENTIC-MCP.md §4).
+     *
+     * Structured (gamma) data collections are not loaded here in v1 — attach
+     * them to the returned object's `data` field yourself if needed.
+     *
+     * @param did     Subject DID whose ethos to read (usually the signed-in owner).
+     * @param opts.zones  Zones to attempt. Defaults to all three.
+     */
+    async buildWorkingSet(did, opts) {
+        const zones = opts?.zones ?? ["public", "circle", "self"];
+        const client = await this.ethos.of(did);
+        const ethos = {};
+        for (const zone of zones) {
+            try {
+                const sections = await client.zone(zone).sections();
+                ethos[zone] = sections.map((s) => ({
+                    id: s.id,
+                    title: s.title,
+                    body: s.body,
+                }));
+            }
+            catch (e) {
+                // Zone not granted / not decryptable for this session → skip it.
+                if (e instanceof AithosSDKError)
+                    continue;
+                throw e;
+            }
+        }
+        return { ethos };
+    }
 }
 //# sourceMappingURL=sdk.js.map

package/dist/test/converse.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=converse.test.d.ts.map

package/dist/test/converse.test.js

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Unit tests for sdk.compute.runConversation with a mock fetch.
+//
+// Mirrors compute.test.ts: a real BrowserIdentity drives the actual
+// envelope-signing path, and we assert on the JSON-RPC body posted to
+// the compute proxy (method name + camelCase→snake_case param mapping).
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDK, AithosSDKError, memoryKeyStore, noopStore, } from "../src/index.js";
+import { serializeRecoveryFile } from "../src/internal/recovery-file.js";
+const APP_DID = "did:aithos:app:test";
+async function makeSdk(fetchImpl) {
+    const id = createBrowserIdentity("test-handle", "Test User");
+    const auth = new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        fetch: (() => {
+            throw new Error("auth not used in converse tests");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+    const { text } = serializeRecoveryFile(id);
+    await auth.signInWithRecovery({ file: text });
+    return new AithosSDK({
+        auth,
+        appDid: APP_DID,
+        endpoints: { compute: "https://compute.example.test" },
+        fetch: fetchImpl,
+    });
+}
+const HAPPY_RESULT = {
+    content: "Voici le résumé.",
+    stopReason: "end_turn",
+    iterations: 2,
+    usage: { inputTokens: 420, outputTokens: 95 },
+    toolCalls: [{ name: "ethos_read_section", ok: true, turn: 1 }],
+    creditsCharged: 130,
+    walletBalance: 99_870,
+    auditId: "audit-cv-1",
+    fundedBy: "purchase",
+};
+describe("compute.runConversation — happy path + param mapping", () => {
+    it("posts aithos.compute_converse with mapped params and parses the result", async () => {
+        let capturedUrl;
+        let capturedInit;
+        const fakeFetch = async (input, init) => {
+            capturedUrl = typeof input === "string" ? input : input.toString();
+            capturedInit = init;
+            return new Response(JSON.stringify({ result: HAPPY_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const sdk = await makeSdk(fakeFetch);
+        const out = await sdk.compute.runConversation({
+            mandateId: "mandate:abc",
+            model: "claude-sonnet-4-6",
+            system: "Tu agis dans la voix de l'utilisateur.",
+            messages: [{ role: "user", content: "Résume mon ethos." }],
+            mcp: { server: "aithos", tools: ["ethos_list_sections", "ethos_read_section"] },
+            workingSet: {
+                ethos: { public: [{ id: "p1", title: "Bio", body: "..." }] },
+            },
+            maxIterations: 5,
+            maxTokens: 800,
+            temperature: 0.4,
+        });
+        assert.deepEqual(out, HAPPY_RESULT);
+        assert.equal(capturedUrl, "https://compute.example.test/v1/invoke");
+        assert.equal(capturedInit?.method, "POST");
+        const body = JSON.parse(capturedInit?.body);
+        assert.equal(body.jsonrpc, "2.0");
+        assert.equal(body.method, "aithos.compute_converse");
+        assert.equal(body.params.app_did, APP_DID);
+        assert.equal(body.params.mandate_id, "mandate:abc");
+        assert.equal(body.params.model, "claude-sonnet-4-6");
+        assert.equal(body.params.system, "Tu agis dans la voix de l'utilisateur.");
+        // camelCase → snake_case mapping on the wire.
+        assert.equal(body.params.max_iterations, 5);
+        assert.equal(body.params.max_tokens, 800);
+        assert.equal(body.params.temperature, 0.4);
+        assert.ok(body.params.working_set, "working_set must be on the wire");
+        assert.deepEqual(body.params.mcp, {
+            server: "aithos",
+            tools: ["ethos_list_sections", "ethos_read_section"],
+        });
+        assert.match(body.params.idempotency_key, /^[0-9a-f]{32}$/);
+        assert.ok(body.params._envelope, "request must carry a signed envelope");
+        // SDK-only camelCase keys must NOT leak onto the wire.
+        assert.equal(body.params.maxIterations, undefined);
+        assert.equal(body.params.workingSet, undefined);
+    });
+    it("omits optional fields when not provided", async () => {
+        let capturedInit;
+        const fakeFetch = async (_input, init) => {
+            capturedInit = init;
+            return new Response(JSON.stringify({ result: HAPPY_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const sdk = await makeSdk(fakeFetch);
+        await sdk.compute.runConversation({
+            mandateId: "mandate:abc",
+            model: "claude-haiku-4-5",
+            messages: [{ role: "user", content: "Salut" }],
+        });
+        const body = JSON.parse(capturedInit?.body);
+        assert.equal(body.params.system, undefined);
+        assert.equal(body.params.mcp, undefined);
+        assert.equal(body.params.working_set, undefined);
+        assert.equal(body.params.max_iterations, undefined);
+        assert.equal(body.params.max_tokens, undefined);
+    });
+});
+describe("compute.runConversation — errors", () => {
+    it("maps a JSON-RPC error to AithosSDKError with the proxy code", async () => {
+        const fakeFetch = async () => new Response(JSON.stringify({
+            error: { code: -32071, message: "insufficient credits" },
+        }), { status: 200, headers: { "content-type": "application/json" } });
+        const sdk = await makeSdk(fakeFetch);
+        await assert.rejects(() => sdk.compute.runConversation({
+            mandateId: "mandate:abc",
+            model: "claude-sonnet-4-6",
+            messages: [{ role: "user", content: "Hi" }],
+        }), (err) => {
+            assert.ok(err instanceof AithosSDKError);
+            assert.equal(err.code, "-32071");
+            return true;
+        });
+    });
+    it("throws sdk_no_signer when no owner and no mandate", async () => {
+        // Build an SDK with no signed-in owner.
+        const auth = new AithosAuth({
+            authBaseUrl: "https://auth.test",
+            fetch: (() => {
+                throw new Error("unused");
+            }),
+            sessionStore: noopStore(),
+            keyStore: memoryKeyStore(),
+        });
+        const sdk = new AithosSDK({
+            auth,
+            appDid: APP_DID,
+            endpoints: { compute: "https://compute.example.test" },
+            fetch: (() => {
+                throw new Error("fetch must not be reached");
+            }),
+        });
+        await assert.rejects(() => sdk.compute.runConversation({
+            model: "claude-sonnet-4-6",
+            messages: [{ role: "user", content: "Hi" }],
+        }), (err) => {
+            assert.ok(err instanceof AithosSDKError);
+            assert.equal(err.code, "sdk_no_signer");
+            return true;
+        });
+    });
+});
+//# sourceMappingURL=converse.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.53",
+  "version": "0.1.0-alpha.54",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",