@aithos/sdk 0.1.0-alpha.55 → 0.1.0-alpha.58

package/dist/test/agent-loop.test.js

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Tests for the pure CLIENT-SIDE agentic loop (ported from the proxy's
+// converse-loop tests, adapted to the async local dispatch + per-turn billing
+// accumulation).
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { runAgenticLoopLocal, } from "../src/index.js";
+function turn(content, stopReason, i = 100, o = 50, credits = 10, balance = 1000) {
+    return {
+        content,
+        stopReason,
+        usage: { inputTokens: i, outputTokens: o },
+        creditsCharged: credits,
+        walletBalance: balance,
+    };
+}
+const okDispatch = async () => ({
+    payload: '{"ok":true}',
+    isError: false,
+});
+describe("runAgenticLoopLocal", () => {
+    it("returns immediately on a single end_turn (no tools)", async () => {
+        let calls = 0;
+        const r = await runAgenticLoopLocal({
+            messages: [{ role: "user", content: "salut" }],
+            maxIterations: 6,
+            invokeTurn: async () => {
+                calls++;
+                return turn([{ type: "text", text: "Réponse directe." }], "end_turn");
+            },
+            dispatch: okDispatch,
+        });
+        assert.equal(r.iterations, 1);
+        assert.equal(r.stopReason, "end_turn");
+        assert.equal(r.finalContent, "Réponse directe.");
+        assert.deepEqual(r.toolCalls, []);
+        assert.equal(calls, 1);
+        assert.equal(r.creditsCharged, 10);
+        assert.equal(r.walletBalance, 1000);
+    });
+    it("runs a tool turn then concludes, summing usage + per-turn credits", async () => {
+        const seq = [
+            turn([
+                { type: "text", text: "je lis" },
+                { type: "tool_use", id: "tu1", name: "ethos_read_section", input: { section_id: "s1" } },
+            ], "tool_use", 100, 20, 7, 993),
+            turn([{ type: "text", text: "Fini." }], "end_turn", 50, 30, 5, 988),
+        ];
+        let n = 0;
+        const dispatched = [];
+        const r = await runAgenticLoopLocal({
+            messages: [{ role: "user", content: "lis s1" }],
+            maxIterations: 6,
+            invokeTurn: async (messages) => {
+                // After the first turn, the running list must carry the assistant
+                // tool_use turn + the user tool_result turn.
+                if (n === 1) {
+                    assert.equal(messages.length, 3);
+                    assert.equal(messages[1].role, "assistant");
+                    assert.equal(messages[2].role, "user");
+                }
+                return seq[n++];
+            },
+            dispatch: async (name) => {
+                dispatched.push(name);
+                return { payload: '{"body":"x"}', isError: false };
+            },
+        });
+        assert.equal(r.iterations, 2);
+        assert.equal(r.stopReason, "end_turn");
+        assert.equal(r.finalContent, "Fini.");
+        assert.deepEqual(dispatched, ["ethos_read_section"]);
+        assert.deepEqual(r.toolCalls, [{ name: "ethos_read_section", ok: true, turn: 1 }]);
+        assert.equal(r.usage.inputTokens, 150);
+        assert.equal(r.usage.outputTokens, 50);
+        assert.equal(r.creditsCharged, 12); // 7 + 5
+        assert.equal(r.walletBalance, 988); // last turn
+    });
+    it("a tool error becomes is_error and does NOT stop the loop", async () => {
+        const seq = [
+            turn([{ type: "tool_use", id: "tu1", name: "ethos_add_section", input: {} }], "tool_use"),
+            turn([{ type: "text", text: "ok malgré erreur" }], "end_turn"),
+        ];
+        let n = 0;
+        const r = await runAgenticLoopLocal({
+            messages: [{ role: "user", content: "ajoute" }],
+            maxIterations: 6,
+            invokeTurn: async () => seq[n++],
+            dispatch: async () => ({ payload: '{"error":"nope"}', isError: true }),
+        });
+        assert.equal(r.stopReason, "end_turn");
+        assert.deepEqual(r.toolCalls, [{ name: "ethos_add_section", ok: false, turn: 1 }]);
+        assert.equal(r.finalContent, "ok malgré erreur");
+    });
+    it("stops at the iteration cap when the model keeps calling tools", async () => {
+        let calls = 0;
+        const r = await runAgenticLoopLocal({
+            messages: [{ role: "user", content: "boucle" }],
+            maxIterations: 3,
+            invokeTurn: async () => {
+                calls++;
+                return turn([
+                    { type: "text", text: `t${calls}` },
+                    { type: "tool_use", id: `tu${calls}`, name: "ethos_list_sections", input: {} },
+                ], "tool_use");
+            },
+            dispatch: okDispatch,
+        });
+        assert.equal(r.stopReason, "max_iterations");
+        assert.equal(r.iterations, 3);
+        assert.equal(calls, 3);
+        assert.equal(r.toolCalls.length, 3);
+        assert.equal(r.finalContent, "t3");
+    });
+});
+//# sourceMappingURL=agent-loop.test.js.map

package/dist/test/agent-tools.test.d.ts

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

package/dist/test/agent-tools.test.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { AITHOS_AGENT_TOOLS, AITHOS_AGENT_READ_TOOLS, AITHOS_AGENT_WRITE_TOOLS, selectAgentTools, isWriteTool, } from "../src/index.js";
+const names = (ts) => ts.map((t) => t.name).sort();
+describe("agent tool catalogue", () => {
+    it("the full catalogue = read + write families", () => {
+        assert.equal(AITHOS_AGENT_TOOLS.length, AITHOS_AGENT_READ_TOOLS.length + AITHOS_AGENT_WRITE_TOOLS.length);
+        assert.deepEqual(names(AITHOS_AGENT_READ_TOOLS), [
+            "data_query",
+            "ethos_list_sections",
+            "ethos_read_section",
+        ]);
+        assert.deepEqual(names(AITHOS_AGENT_WRITE_TOOLS), [
+            "ethos_add_section",
+            "ethos_delete_section",
+            "ethos_update_section",
+        ]);
+    });
+    it("every tool has a name, description, and object input_schema", () => {
+        for (const t of AITHOS_AGENT_TOOLS) {
+            assert.ok(t.name.length > 0);
+            assert.ok(t.description.length > 0);
+            assert.equal(typeof t.input_schema, "object");
+            assert.equal(t.input_schema.type, "object");
+        }
+    });
+    it("isWriteTool flags only the write family", () => {
+        assert.equal(isWriteTool("ethos_add_section"), true);
+        assert.equal(isWriteTool("ethos_update_section"), true);
+        assert.equal(isWriteTool("ethos_delete_section"), true);
+        assert.equal(isWriteTool("ethos_read_section"), false);
+        assert.equal(isWriteTool("data_query"), false);
+        assert.equal(isWriteTool("bogus"), false);
+    });
+    it("selectAgentTools: default = full catalogue", () => {
+        assert.equal(selectAgentTools().length, AITHOS_AGENT_TOOLS.length);
+        assert.equal(selectAgentTools({}).length, AITHOS_AGENT_TOOLS.length);
+        assert.equal(selectAgentTools({ tools: [] }).length, AITHOS_AGENT_TOOLS.length);
+    });
+    it("selectAgentTools: readOnly = read family only", () => {
+        assert.deepEqual(names(selectAgentTools({ readOnly: true })), names(AITHOS_AGENT_READ_TOOLS));
+    });
+    it("selectAgentTools: subset by name, unknown names ignored", () => {
+        const sel = selectAgentTools({ tools: ["ethos_add_section", "nope", "data_query"] });
+        assert.deepEqual(names(sel), ["data_query", "ethos_add_section"]);
+    });
+});
+//# sourceMappingURL=agent-tools.test.js.map

package/dist/test/invoke-turn-sdk.test.d.ts

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

package/dist/test/invoke-turn-sdk.test.js

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Wire tests for sdk.compute.invokeTurn + sdk.compute.runConversationLocal,
+// mirroring converse.test.ts: a real BrowserIdentity drives envelope signing
+// and we assert on the JSON-RPC body posted to the proxy.
+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, AITHOS_AGENT_TOOLS, } 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("turn-handle", "Turn User");
+    const auth = new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        fetch: (() => {
+            throw new Error("auth not used");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+    const { text } = serializeRecoveryFile(id);
+    await auth.signInWithRecovery({ file: text });
+    const sdk = new AithosSDK({
+        auth,
+        appDid: APP_DID,
+        endpoints: { compute: "https://compute.example.test" },
+        fetch: fetchImpl,
+    });
+    return { sdk, did: id.did };
+}
+const TURN_RESULT = {
+    content: [{ type: "text", text: "Réponse." }],
+    stopReason: "end_turn",
+    usage: { inputTokens: 100, outputTokens: 20 },
+    creditsCharged: 12,
+    walletBalance: 9_988,
+    auditId: "audit-turn-1",
+    fundedBy: "purchase",
+};
+describe("compute.invokeTurn — wire", () => {
+    it("posts aithos.compute_invoke_turn with tools + mapped params", 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: TURN_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const { sdk } = await makeSdk(fakeFetch);
+        const out = await sdk.compute.invokeTurn({
+            mandateId: "mandate:abc",
+            model: "claude-sonnet-4-6",
+            system: "sys",
+            messages: [{ role: "user", content: "salut" }],
+            tools: [
+                {
+                    name: "ethos_list_sections",
+                    description: "list",
+                    input_schema: { type: "object", properties: {} },
+                },
+            ],
+            maxTokens: 512,
+            temperature: 0.2,
+        });
+        assert.deepEqual(out, TURN_RESULT);
+        assert.equal(capturedUrl, "https://compute.example.test/v1/invoke");
+        const body = JSON.parse(capturedInit?.body);
+        assert.equal(body.method, "aithos.compute_invoke_turn");
+        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, "sys");
+        assert.equal(body.params.max_tokens, 512);
+        assert.equal(body.params.temperature, 0.2);
+        assert.ok(Array.isArray(body.params.tools), "tools must be on the wire");
+        assert.equal(body.params.tools.length, 1);
+        assert.match(body.params.idempotency_key, /^[0-9a-f]{32}$/);
+        assert.ok(body.params._envelope, "must carry a signed envelope");
+        // SDK-only camelCase keys must not leak.
+        assert.equal(body.params.maxTokens, undefined);
+    });
+    it("maps a JSON-RPC error to AithosSDKError", 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.invokeTurn({
+            model: "claude-sonnet-4-6",
+            messages: [{ role: "user", content: "hi" }],
+            tools: [],
+        }), (err) => {
+            assert.ok(err instanceof AithosSDKError);
+            assert.equal(err.code, "-32071");
+            return true;
+        });
+    });
+});
+describe("compute.runConversationLocal — wiring", () => {
+    it("drives the loop: single end_turn → 1 iteration, full catalogue forwarded", async () => {
+        const bodies = [];
+        const fakeFetch = async (_input, init) => {
+            bodies.push(JSON.parse(init?.body));
+            return new Response(JSON.stringify({ result: TURN_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const { sdk } = await makeSdk(fakeFetch);
+        const out = await sdk.compute.runConversationLocal({
+            model: "claude-sonnet-4-6",
+            messages: [{ role: "user", content: "Mets à jour ma bio si besoin." }],
+            system: "Écris seulement si nécessaire.",
+        });
+        assert.equal(out.iterations, 1);
+        assert.equal(out.stopReason, "end_turn");
+        assert.equal(out.content, "Réponse.");
+        assert.equal(out.creditsCharged, 12);
+        assert.equal(out.walletBalance, 9_988);
+        assert.equal(out.auditId, "audit-turn-1");
+        assert.equal(out.fundedBy, "purchase");
+        assert.deepEqual(out.toolCalls, []);
+        // One proxy turn, the right method, the full tool catalogue forwarded.
+        assert.equal(bodies.length, 1);
+        assert.equal(bodies[0].method, "aithos.compute_invoke_turn");
+        assert.equal(bodies[0].params.tools.length, AITHOS_AGENT_TOOLS.length);
+    });
+    it("readOnly forwards only the read family", async () => {
+        const bodies = [];
+        const fakeFetch = async (_input, init) => {
+            bodies.push(JSON.parse(init?.body));
+            return new Response(JSON.stringify({ result: TURN_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const { sdk } = await makeSdk(fakeFetch);
+        await sdk.compute.runConversationLocal({
+            model: "claude-sonnet-4-6",
+            messages: [{ role: "user", content: "résume" }],
+            readOnly: true,
+        });
+        const toolNames = bodies[0].params.tools.map((t) => t.name).sort();
+        assert.deepEqual(toolNames, ["data_query", "ethos_list_sections", "ethos_read_section"]);
+    });
+    it("throws sdk_no_signer when no owner and no mandate/subject", async () => {
+        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.runConversationLocal({
+            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=invoke-turn-sdk.test.js.map

package/dist/test/owner-data-client.test.d.ts

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

package/dist/test/owner-data-client.test.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Phase D — auth.ownerDataClient() returns a session-bound data client that
+// signs + seals under the dedicated #data sphere (not #root). This is the
+// ergonomic factory apps use so collections are created under #data by default.
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { AithosAuth, memoryKeyStore, noopStore } from "../src/index.js";
+import { serializeRecoveryFile } from "../src/internal/recovery-file.js";
+import { ed25519SeedToX25519PrivateKey, tryUnwrapCmk, } from "../src/internal/cmk-wrap.js";
+function makePds() {
+    const collections = new Map();
+    const records = new Map();
+    const fetchImpl = (async (_url, init) => {
+        const body = JSON.parse(init.body);
+        const p = body.params ?? {};
+        const ok = (r) => new Response(JSON.stringify({ jsonrpc: "2.0", id: body.id, result: r }), { status: 200 });
+        const er = (c, m) => new Response(JSON.stringify({ jsonrpc: "2.0", id: body.id, error: { code: c, message: m } }), { status: 200 });
+        const urn = (d, n) => `urn:aithos:collection:${d}:${n}`;
+        switch (body.method) {
+            case "aithos.data.create_collection": {
+                const u = urn(p.subject_did, p.collection_name);
+                collections.set(u, { urn: u, name: p.collection_name, schema: p.schema, subject_did: p.subject_did, cmk_envelope: p.cmk_envelope, record_count: 0 });
+                records.set(u, new Map());
+                return ok({ urn: u, name: p.collection_name, schema: p.schema, cmk_envelope: p.cmk_envelope });
+            }
+            case "aithos.data.get_collection": {
+                const c = collections.get(urn(p.subject_did, p.collection_name));
+                return c ? ok({ urn: c.urn, name: c.name, schema: c.schema, cmk_envelope: c.cmk_envelope, record_count: c.record_count }) : er(-32020, "nf");
+            }
+            case "aithos.data.insert_record": {
+                records.get(p.collection_urn).set(p.record_id, { record_id: p.record_id, metadata: p.metadata, payload: p.payload });
+                return ok({ record_id: p.record_id });
+            }
+            case "aithos.data.get_record": {
+                const r = records.get(p.collection_urn)?.get(p.record_id);
+                return r ? ok(r) : er(-32020, "nf");
+            }
+            default:
+                return er(-32601, body.method);
+        }
+    });
+    return { fetchImpl, collections };
+}
+function authWith(fetchImpl) {
+    return new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        apiBaseUrl: "https://api.test",
+        fetch: fetchImpl,
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+}
+test("ownerDataClient seals collections under #data (not #root)", async () => {
+    const id = createBrowserIdentity("phased", "Phase D");
+    assert.ok(id.data, "fresh identity has #data");
+    const { text } = serializeRecoveryFile(id);
+    const pds = makePds();
+    const auth = authWith(pds.fetchImpl);
+    await auth.signInWithRecovery({ file: text });
+    const data = auth.ownerDataClient({ pdsUrl: "https://pds.test" });
+    await data.createCollection({ name: "contacts", schema: "aithos.contacts.v1" });
+    const recId = await data.collection("contacts").insert({ name: "Iris", phone: "+33-phaseD" });
+    // Round-trips under #data.
+    const got = await data.collection("contacts").get(recId);
+    assert.equal(got.phone, "+33-phaseD");
+    // The owner wrap opens with #data and NOT with #root → proves the sealing key.
+    const urn = `urn:aithos:collection:${id.did}:contacts`;
+    const env = pds.collections.get(urn).cmk_envelope;
+    const ownerWrap = env.wraps.find((w) => w.recipient === `${id.did}#data-kex`);
+    const opensWithData = tryUnwrapCmk({ wrap: ownerWrap, collectionUrn: urn, privateKey: ed25519SeedToX25519PrivateKey(id.data.seed) });
+    const opensWithRoot = tryUnwrapCmk({ wrap: ownerWrap, collectionUrn: urn, privateKey: ed25519SeedToX25519PrivateKey(id.root.seed) });
+    assert.ok(opensWithData, "owner wrap opens with #data");
+    assert.equal(opensWithRoot, null, "owner wrap does NOT open with #root");
+});
+test("ownerDataClient throws for a legacy account (no #data sphere)", async () => {
+    const id = { ...createBrowserIdentity("legacy", "Legacy"), data: undefined };
+    const { text } = serializeRecoveryFile(id);
+    const auth = authWith(makePds().fetchImpl);
+    await auth.signInWithRecovery({ file: text });
+    assert.throws(() => auth.ownerDataClient(), /no #data sphere/);
+});
+test("ownerDataClient throws when no owner is signed in", () => {
+    const auth = authWith(makePds().fetchImpl);
+    assert.throws(() => auth.ownerDataClient(), /no owner is signed in/);
+});
+//# sourceMappingURL=owner-data-client.test.js.map

package/dist/test/schema-autoresolve.test.js

@@ -109,7 +109,7 @@ test("a reader without the bundled vendor lite decodes via the published schema"
     assert.equal(got.title, "Hello", "indexable field present");
     assert.equal(got.body, "top secret body", "encrypted field decoded via auto-resolved schema");
 });
-test("a reader still fails cleanly when the schema is neither bundled nor published", async () => {
+test("schema-less READ still works (decrypts); only WRITE requires the schema", async () => {
     const seed = new Uint8Array(randomBytes(32));
     const pub = ed.getPublicKey(seed);
     let n = 0n;
@@ -126,11 +126,21 @@ test("a reader still fails cleanly when the schema is neither bundled nor publis
     const did = `did:key:z${mb}`;
     const vm = `${did}#z${mb}`;
     const pds = makePds();
-    // Writer creates the collection WITHOUT registering the schema on the PDS.
+    // Writer bundles the lite, creates the collection + a record, but does NOT
+    // register the schema on the PDS (simulates an app like delie that keeps its
+    // schema local). So no client can auto-resolve it.
     const writer = createDataClient({ pdsUrl: "https://pds.test", did, sphereSeed: seed, verificationMethod: vm, schemas: [memoLite], fetch: pds.fetchImpl });
     await writer.createCollection({ name: "memos", schema: MEMO_ID });
-    await writer.collection("memos").insert({ title: "x", body: "y" });
+    const recId = await writer.collection("memos").insert({ title: "Hi", body: "encrypted secret" });
+    // Reader has NEITHER the bundled lite NOR a published schema to fetch.
     const reader = createDataClient({ pdsUrl: "https://pds.test", did, sphereSeed: seed, verificationMethod: vm, fetch: pds.fetchImpl });
-    await assert.rejects(() => reader.collection("memos").get("anything"), /not known to the SDK and not published/);
+    // READ still works — records decrypt from the CMK + metadata/payload; the
+    // schema is only needed to SPLIT on write. This is what makes a migrated
+    // collection directly usable under #data by any client.
+    const got = await reader.collection("memos").get(recId);
+    assert.equal(got.title, "Hi", "indexable field (plaintext metadata) present");
+    assert.equal(got.body, "encrypted secret", "encrypted field decrypted WITHOUT the schema");
+    // WRITE fails cleanly (can't split/validate without the schema).
+    await assert.rejects(() => reader.collection("memos").insert({ title: "no", body: "go" }), /needs its schema/);
 });
 //# sourceMappingURL=schema-autoresolve.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.55",
+  "version": "0.1.0-alpha.58",
   "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",