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

package/dist/src/auth.d.ts

@@ -420,7 +420,7 @@ export declare class AithosAuth {
          * Choose `"root"`, `"circle"`, or `"self"` only if the receiving
          * server specifically expects one of those (rare).
          */
-        readonly sphere?: "root" | "public" | "circle" | "self";
+        readonly sphere?: "root" | "public" | "circle" | "self" | "data";
         /**
          * Envelope lifetime in seconds. Default 60. Aithos servers cap
          * at 300; third-party servers may apply their own cap.

package/dist/src/auth.js

@@ -192,8 +192,9 @@ export class AithosAuth {
         if (sphere !== "root" &&
             sphere !== "public" &&
             sphere !== "circle" &&
-            sphere !== "self") {
-            throw new AithosSDKError("auth_invalid_sphere", `signEnvelope: invalid sphere "${sphere}". Expected one of: root, public, circle, self.`);
+            sphere !== "self" &&
+            sphere !== "data") {
+            throw new AithosSDKError("auth_invalid_sphere", `signEnvelope: invalid sphere "${sphere}". Expected one of: root, public, circle, self, data.`);
         }
         const signer = this.#ownerSigners.signerForSphere(sphere);
         return signOwnerEnvelope({
@@ -412,6 +413,7 @@ export class AithosAuth {
                 public: identity.public.seed,
                 circle: identity.circle.seed,
                 self: identity.self.seed,
+                ...(identity.data ? { data: identity.data.seed } : {}),
             },
             delegates: [],
         });
@@ -462,6 +464,7 @@ export class AithosAuth {
                 public: bytesToHex(identity.public.seed),
                 circle: bytesToHex(identity.circle.seed),
                 self: bytesToHex(identity.self.seed),
+                ...(identity.data ? { data: bytesToHex(identity.data.seed) } : {}),
             },
             savedAt: new Date().toISOString(),
         });
@@ -833,6 +836,7 @@ export class AithosAuth {
                     public: identity.public.seed,
                     circle: identity.circle.seed,
                     self: identity.self.seed,
+                    ...(identity.data ? { data: identity.data.seed } : {}),
                 },
                 delegates: [],
             });
@@ -869,6 +873,7 @@ export class AithosAuth {
                 public: bytesToHex(identity.public.seed),
                 circle: bytesToHex(identity.circle.seed),
                 self: bytesToHex(identity.self.seed),
+                ...(identity.data ? { data: bytesToHex(identity.data.seed) } : {}),
             },
             savedAt: new Date().toISOString(),
         });

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/internal/owner-signers.d.ts

@@ -17,6 +17,8 @@ export declare class OwnerSigners {
     readonly public: Signer;
     readonly circle: Signer;
     readonly self: Signer;
+    /** Optional dedicated #data sphere signer (absent on legacy owners). */
+    readonly data?: Signer;
     constructor(args: {
         did: string;
         handle: string;
@@ -25,6 +27,7 @@ export declare class OwnerSigners {
         public: Signer;
         circle: Signer;
         self: Signer;
+        data?: Signer;
     });
     /**
      * Build from a {@link BrowserIdentity}. The seeds inside `identity`
@@ -59,7 +62,7 @@ export declare class OwnerSigners {
      * have the sphere as a string ("public" | "circle" | "self") rather
      * than a typed accessor.
      */
-    signerForSphere(sphere: "root" | "public" | "circle" | "self"): Signer;
+    signerForSphere(sphere: "root" | "public" | "circle" | "self" | "data"): Signer;
     /**
      * Internal — project to a {@link StoredIdentity} for protocol-client
      * interop. Reads seed bytes via {@link RawSeedSigner._unsafeKeyPair}
@@ -71,7 +74,7 @@ export declare class OwnerSigners {
      * @internal
      */
     _unsafeStoredIdentity(): StoredIdentity;
-    /** Zeroize all four private seeds. Idempotent. */
+    /** Zeroize all private seeds. Idempotent. */
     destroy(): void;
     get destroyed(): boolean;
 }

package/dist/src/internal/owner-signers.js

@@ -34,6 +34,8 @@ export class OwnerSigners {
     public;
     circle;
     self;
+    /** Optional dedicated #data sphere signer (absent on legacy owners). */
+    data;
     #destroyed = false;
     constructor(args) {
         this.did = args.did;
@@ -43,6 +45,7 @@ export class OwnerSigners {
         this.public = args.public;
         this.circle = args.circle;
         this.self = args.self;
+        this.data = args.data;
     }
     /**
      * Build from a {@link BrowserIdentity}. The seeds inside `identity`
@@ -59,6 +62,11 @@ export class OwnerSigners {
             public: new RawSeedSigner(identity.public.seed, identity.public.publicKey),
             circle: new RawSeedSigner(identity.circle.seed, identity.circle.publicKey),
             self: new RawSeedSigner(identity.self.seed, identity.self.publicKey),
+            ...(identity.data
+                ? {
+                    data: new RawSeedSigner(identity.data.seed, identity.data.publicKey),
+                }
+                : {}),
         });
     }
     /**
@@ -120,6 +128,11 @@ export class OwnerSigners {
                 return this.circle;
             case "self":
                 return this.self;
+            case "data":
+                if (!this.data) {
+                    throw new Error("OwnerSigners: this owner has no #data sphere (legacy account)");
+                }
+                return this.data;
         }
     }
     /**
@@ -146,11 +159,18 @@ export class OwnerSigners {
                 public: bytesToHexLocal(asRawSeed(this.public, "public")._unsafeKeyPair().seed),
                 circle: bytesToHexLocal(asRawSeed(this.circle, "circle")._unsafeKeyPair().seed),
                 self: bytesToHexLocal(asRawSeed(this.self, "self")._unsafeKeyPair().seed),
+                // Preserve the optional #data seed on vault re-encryption — dropping it
+                // here would silently lose the data sphere on the next delegate-add.
+                ...(this.data
+                    ? {
+                        data: bytesToHexLocal(asRawSeed(this.data, "data")._unsafeKeyPair().seed),
+                    }
+                    : {}),
             },
             savedAt: new Date().toISOString(),
         };
     }
-    /** Zeroize all four private seeds. Idempotent. */
+    /** Zeroize all private seeds. Idempotent. */
     destroy() {
         if (this.#destroyed)
             return;
@@ -158,6 +178,7 @@ export class OwnerSigners {
         this.public.destroy();
         this.circle.destroy();
         this.self.destroy();
+        this.data?.destroy();
         this.#destroyed = true;
     }
     get destroyed() {

package/dist/src/internal/recovery-file.d.ts

@@ -8,6 +8,8 @@ export interface ParsedRecoveryFile {
         readonly public: string;
         readonly circle: string;
         readonly self: string;
+        /** Optional dedicated #data sphere seed (absent on legacy recovery files). */
+        readonly data?: string;
     };
 }
 /**

package/dist/src/internal/recovery-file.js

@@ -44,6 +44,11 @@ export function parseRecoveryFile(text) {
             throw bad(`seeds_hex.${k}: expected 64-char lowercase hex`);
         }
     }
+    // #data is optional (absent on legacy recovery files); validate when present.
+    const dataSeed = seeds["data"];
+    if (dataSeed !== undefined && (typeof dataSeed !== "string" || !HEX_64.test(dataSeed))) {
+        throw bad("seeds_hex.data: expected 64-char lowercase hex");
+    }
     return {
         handle,
         displayName,
@@ -53,6 +58,7 @@ export function parseRecoveryFile(text) {
             public: seeds["public"],
             circle: seeds["circle"],
             self: seeds["self"],
+            ...(typeof dataSeed === "string" ? { data: dataSeed } : {}),
         },
     };
 }
@@ -78,6 +84,7 @@ export function serializeRecoveryFile(identity) {
             public: bytesToHex(identity.public.seed),
             circle: bytesToHex(identity.circle.seed),
             self: bytesToHex(identity.self.seed),
+            ...(identity.data ? { data: bytesToHex(identity.data.seed) } : {}),
         },
         saved_at: new Date().toISOString(),
     };

package/dist/src/key-store.d.ts

@@ -19,6 +19,12 @@ export interface StoredOwnerKeys {
         readonly public: string;
         readonly circle: string;
         readonly self: string;
+        /**
+         * Optional dedicated #data sphere seed (spec/data/02-key-hierarchy.md).
+         * Present on owners created since the #data sphere landed; absent on legacy
+         * owners (which sign data/asset PDS ops under #root).
+         */
+        readonly data?: string;
     };
     /** ISO-8601 timestamp of the original save. Informational. */
     readonly savedAt: string;

package/dist/src/key-store.js

@@ -213,6 +213,12 @@ function validOwnerOrNull(v) {
         if (s[k].length !== 64)
             return null;
     }
+    // #data is optional (absent on legacy owners); validate only when present.
+    if (s["data"] !== undefined) {
+        if (typeof s["data"] !== "string" || s["data"].length !== 64) {
+            return null;
+        }
+    }
     if (typeof o["savedAt"] !== "string")
         return null;
     return o;

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/dist/test/data-sphere.test.d.ts

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

package/dist/test/data-sphere.test.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Tests for the optional #data sphere through the SDK's owner key material:
+// the recovery file and OwnerSigners (vault re-encryption projection).
+// Mirrors the protocol-core / protocol-client data-sphere tests.
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { OwnerSigners } from "../src/internal/owner-signers.js";
+import { serializeRecoveryFile, parseRecoveryFile, } from "../src/internal/recovery-file.js";
+describe("#data sphere — recovery file", () => {
+    it("round-trips the #data seed for a fresh (eager) identity", () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        assert.ok(id.data, "createBrowserIdentity should be eager about #data");
+        const { text } = serializeRecoveryFile(id);
+        const parsed = parseRecoveryFile(text);
+        assert.equal(typeof parsed.seedsHex.data, "string");
+        assert.equal(parsed.seedsHex.data.length, 64);
+    });
+    it("legacy identity without #data serializes/parses without a data seed", () => {
+        const id = { ...createBrowserIdentity("dave", "Dave"), data: undefined };
+        const { text } = serializeRecoveryFile(id);
+        const parsed = parseRecoveryFile(text);
+        assert.equal(parsed.seedsHex.data, undefined);
+    });
+});
+describe("#data sphere — OwnerSigners", () => {
+    it("preserves the #data seed on the vault re-encryption projection", () => {
+        const id = createBrowserIdentity("bob", "Bob");
+        const signers = OwnerSigners.fromBrowserIdentity(id);
+        try {
+            // _unsafeStoredIdentity() is what the vault re-encryption path reads —
+            // dropping #data here would silently lose the sphere on delegate-add.
+            const projected = signers._unsafeStoredIdentity();
+            assert.ok(projected.seeds.data, "#data seed must survive projection");
+            // signerForSphere exposes the #data signer.
+            assert.ok(signers.data, "OwnerSigners.data signer should be present");
+            assert.equal(signers.signerForSphere("data"), signers.data);
+        }
+        finally {
+            signers.destroy();
+        }
+    });
+    it("legacy owner (no #data) → no data signer, signerForSphere('data') throws", () => {
+        const id = { ...createBrowserIdentity("erin", "Erin"), data: undefined };
+        const signers = OwnerSigners.fromBrowserIdentity(id);
+        try {
+            assert.equal(signers.data, undefined);
+            assert.equal(signers._unsafeStoredIdentity().seeds.data, undefined);
+            assert.throws(() => signers.signerForSphere("data"), /no #data sphere/);
+        }
+        finally {
+            signers.destroy();
+        }
+    });
+});
+//# sourceMappingURL=data-sphere.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.52",
+  "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",
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "@aithos/assets-crypto": ">=0.1.0-alpha.1 <0.2.0",
-    "@aithos/protocol-client": "^0.1.0-alpha.18",
+    "@aithos/protocol-client": "^0.1.0-alpha.19",
     "@aithos/protocol-core": ">=0.6.5 <0.7.0",
     "react": "^18.0.0 || ^19.0.0"
   },
@@ -71,7 +71,7 @@
   },
   "devDependencies": {
     "@aithos/assets-crypto": "^0.1.0-alpha.1",
-    "@aithos/protocol-client": "^0.1.0-alpha.18",
+    "@aithos/protocol-client": "^0.1.0-alpha.19",
     "@aithos/protocol-core": ">=0.6.5 <0.7.0",
     "@types/node": "^24.12.2",
     "fake-indexeddb": "^6.2.5",