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

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

@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Tests for the CLIENT-SIDE local tool dispatch: read navigation, write
+// staging + publish, and the ethos.write.* authorisation gate. The EthosClient
+// is faked (no network) — we assert on what got staged/published and on the
+// is_error outcomes for out-of-scope or malformed calls.
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { dispatchAgentToolLocal, AithosSDKError, } from "../src/index.js";
+/**
+ * Build a fake EthosClient. `zones` maps zone→sections (a zone absent from the
+ * map is treated as unreadable and throws like an ungranted/undecryptable
+ * zone, exercising the dispatch's skip-on-error path).
+ */
+function fakeEthos(mode, zones) {
+    const state = { staged: [], publishes: 0 };
+    const client = {
+        mode,
+        subjectDid: "did:aithos:subject",
+        zone(name) {
+            return {
+                async sections() {
+                    const s = zones[name];
+                    if (!s) {
+                        throw new AithosSDKError("ethos_zone_unreadable", `cannot read ${name}`);
+                    }
+                    return s;
+                },
+                addSection(input) {
+                    state.staged.push({ op: "add", zone: name, arg: input });
+                },
+                updateSection(id, patch) {
+                    state.staged.push({ op: "update", zone: name, arg: { id, patch } });
+                },
+                deleteSection(id) {
+                    state.staged.push({ op: "delete", zone: name, arg: { id } });
+                },
+            };
+        },
+        async publish() {
+            state.publishes++;
+            return {
+                editionHeight: 2,
+                manifestHash: "",
+                subjectDid: "did:aithos:subject",
+                zonesPublished: [],
+            };
+        },
+    };
+    return { client, state };
+}
+function ownerCtx(zones) {
+    const { client, state } = fakeEthos("owner", zones);
+    return { ctx: { ethos: client, delegateScopes: [] }, state };
+}
+function delegateCtx(zones, scopes) {
+    const { client, state } = fakeEthos("delegate", zones);
+    return { ctx: { ethos: client, delegateScopes: scopes }, state };
+}
+const parse = (o) => JSON.parse(o.payload);
+describe("dispatch — reads", () => {
+    it("ethos_list_sections aggregates readable zones (skips unreadable)", async () => {
+        const { ctx } = ownerCtx({
+            public: [{ id: "p1", title: "Bio", body: "..." }],
+            // circle absent → unreadable → skipped
+            self: [{ id: "s1", title: "Secret", body: "..." }],
+        });
+        const out = await dispatchAgentToolLocal(ctx, "ethos_list_sections", {});
+        assert.equal(out.isError, false);
+        const { sections } = parse(out);
+        assert.deepEqual(sections.sort((a, b) => a.id.localeCompare(b.id)), [
+            { zone: "public", id: "p1", title: "Bio" },
+            { zone: "self", id: "s1", title: "Secret" },
+        ]);
+    });
+    it("ethos_read_section returns body for a readable section", async () => {
+        const { ctx } = ownerCtx({ public: [{ id: "p1", title: "Bio", body: "hello" }] });
+        const out = await dispatchAgentToolLocal(ctx, "ethos_read_section", { section_id: "p1" });
+        assert.equal(out.isError, false);
+        assert.deepEqual(parse(out), { zone: "public", title: "Bio", body: "hello" });
+    });
+    it("ethos_read_section is_error for unknown id", async () => {
+        const { ctx } = ownerCtx({ public: [] });
+        const out = await dispatchAgentToolLocal(ctx, "ethos_read_section", { section_id: "nope" });
+        assert.equal(out.isError, true);
+    });
+    it("data_query is_error without a data provider", async () => {
+        const { ctx } = ownerCtx({ public: [] });
+        const out = await dispatchAgentToolLocal(ctx, "data_query", { collection: "contacts" });
+        assert.equal(out.isError, true);
+    });
+    it("data_query uses the provider when present (limit clamped)", async () => {
+        const { client } = fakeEthos("owner", { public: [] });
+        let seenLimit = -1;
+        const ctx = {
+            ethos: client,
+            delegateScopes: [],
+            dataProvider: async (_c, limit) => {
+                seenLimit = limit;
+                return [{ a: 1 }];
+            },
+        };
+        const out = await dispatchAgentToolLocal(ctx, "data_query", { collection: "c", limit: 999 });
+        assert.equal(out.isError, false);
+        assert.equal(seenLimit, 100); // clamped to max
+        assert.deepEqual(parse(out).records, [{ a: 1 }]);
+    });
+});
+describe("dispatch — writes (owner)", () => {
+    it("ethos_add_section stages + publishes", async () => {
+        const { ctx, state } = ownerCtx({ public: [] });
+        const out = await dispatchAgentToolLocal(ctx, "ethos_add_section", {
+            zone: "public",
+            title: "New",
+            body: "content",
+        });
+        assert.equal(out.isError, false);
+        assert.equal(parse(out).published, true);
+        assert.equal(state.publishes, 1);
+        assert.deepEqual(state.staged, [
+            { op: "add", zone: "public", arg: { title: "New", body: "content" } },
+        ]);
+    });
+    it("ethos_update_section locates the zone then publishes", async () => {
+        const { ctx, state } = ownerCtx({
+            circle: [{ id: "c1", title: "Old", body: "x" }],
+        });
+        const out = await dispatchAgentToolLocal(ctx, "ethos_update_section", {
+            section_id: "c1",
+            body: "new body",
+        });
+        assert.equal(out.isError, false);
+        assert.equal(parse(out).zone, "circle");
+        assert.equal(state.publishes, 1);
+        assert.deepEqual(state.staged[0], {
+            op: "update",
+            zone: "circle",
+            arg: { id: "c1", patch: { body: "new body" } },
+        });
+    });
+    it("ethos_delete_section locates the zone then publishes", async () => {
+        const { ctx, state } = ownerCtx({ self: [{ id: "s9", title: "T", body: "B" }] });
+        const out = await dispatchAgentToolLocal(ctx, "ethos_delete_section", { section_id: "s9" });
+        assert.equal(out.isError, false);
+        assert.equal(parse(out).zone, "self");
+        assert.equal(state.publishes, 1);
+    });
+    it("invalid zone / missing fields → is_error, nothing published", async () => {
+        const { ctx, state } = ownerCtx({ public: [] });
+        const bad = await dispatchAgentToolLocal(ctx, "ethos_add_section", {
+            zone: "nope",
+            title: "x",
+            body: "y",
+        });
+        assert.equal(bad.isError, true);
+        const noTitle = await dispatchAgentToolLocal(ctx, "ethos_add_section", {
+            zone: "public",
+            body: "y",
+        });
+        assert.equal(noTitle.isError, true);
+        assert.equal(state.publishes, 0);
+    });
+    it("update with nothing to change → is_error", async () => {
+        const { ctx } = ownerCtx({ public: [{ id: "p1", title: "T", body: "B" }] });
+        const out = await dispatchAgentToolLocal(ctx, "ethos_update_section", { section_id: "p1" });
+        assert.equal(out.isError, true);
+    });
+});
+describe("dispatch — write authorisation gate (delegate)", () => {
+    it("publishes when the mandate grants ethos.write.<zone>", async () => {
+        const { ctx, state } = delegateCtx({ public: [] }, ["ethos.write.public"]);
+        const out = await dispatchAgentToolLocal(ctx, "ethos_add_section", {
+            zone: "public",
+            title: "T",
+            body: "B",
+        });
+        assert.equal(out.isError, false);
+        assert.equal(state.publishes, 1);
+    });
+    it("refuses (is_error, no publish) when the write scope is missing", async () => {
+        const { ctx, state } = delegateCtx({ self: [] }, ["ethos.write.public"]);
+        const out = await dispatchAgentToolLocal(ctx, "ethos_add_section", {
+            zone: "self",
+            title: "T",
+            body: "B",
+        });
+        assert.equal(out.isError, true);
+        assert.match(parse(out).error, /ethos\.write\.self/);
+        assert.equal(state.publishes, 0);
+        assert.equal(state.staged.length, 0);
+    });
+    it("update refuses when write scope for the located zone is missing", async () => {
+        const { ctx, state } = delegateCtx({ circle: [{ id: "c1", title: "T", body: "B" }] }, ["ethos.write.public"]);
+        const out = await dispatchAgentToolLocal(ctx, "ethos_update_section", {
+            section_id: "c1",
+            body: "new",
+        });
+        assert.equal(out.isError, true);
+        assert.equal(state.publishes, 0);
+    });
+});
+describe("dispatch — anonymous cannot write", () => {
+    it("ethos_add_section is_error for anonymous", async () => {
+        const { client, state } = fakeEthos("anonymous", { public: [] });
+        const ctx = { ethos: client, delegateScopes: [] };
+        const out = await dispatchAgentToolLocal(ctx, "ethos_add_section", {
+            zone: "public",
+            title: "T",
+            body: "B",
+        });
+        assert.equal(out.isError, true);
+        assert.equal(state.publishes, 0);
+    });
+});
+describe("dispatch — unknown tool", () => {
+    it("returns is_error for an unknown tool name", async () => {
+        const { ctx } = ownerCtx({ public: [] });
+        const out = await dispatchAgentToolLocal(ctx, "bogus_tool", {});
+        assert.equal(out.isError, true);
+    });
+});
+//# sourceMappingURL=agent-dispatch.test.js.map

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

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

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/auth-j3.test.js

@@ -90,7 +90,7 @@ describe("recovery file: parse + serialize", () => {
 /*  parseDelegateBundle                                                       */
 /* -------------------------------------------------------------------------- */
 describe("delegate bundle: parse", () => {
-    it("parses a well-formed bundle", () => {
+    it("parses a well-formed bundle (legacy subject_did field)", () => {
         const text = delegateBundleText({
             mandateId: "mandate:01H8XYZ",
             subjectDid: "did:aithos:zCarol",
@@ -103,6 +103,37 @@ describe("delegate bundle: parse", () => {
         assert.equal(parsed.granteeId, "urn:aithos:agent:bob1");
         assert.equal(parsed.delegateSeedHex.length, 64);
     });
+    it("parses a bundle minted by mintDelegateBundle (issuer field)", () => {
+        // Real wire shape emitted by `mintDelegateBundle` in protocol-client:
+        // SignedMandate carries the subject's DID under `issuer`, NOT
+        // `subject_did`. Regression test for the import flow that broke
+        // every freshly-minted mandate before this fix.
+        const text = JSON.stringify({
+            aithos_delegate_version: "0.1.0",
+            mandate: {
+                "aithos-mandate": "0.1",
+                id: "mandate:01H8ISSUER",
+                issuer: "did:aithos:zCarol",
+                issued_by_key: "did:aithos:zCarol#root",
+                grantee: {
+                    id: "urn:aithos:agent:bob1",
+                    pubkey: "z6MkqGenericPubKey",
+                },
+                actor_sphere: "self",
+                scopes: ["ethos.read.public", "ethos.write.public"],
+                not_before: "2026-05-10T00:00:00Z",
+                not_after: "2026-05-11T00:00:00Z",
+                issued_at: "2026-05-10T00:00:00Z",
+                nonce: "abc",
+                signature: { alg: "ed25519", key: "...", value: "..." },
+            },
+            delegate_seed_hex: "11".repeat(32),
+        });
+        const parsed = parseDelegateBundle(text);
+        assert.equal(parsed.subjectDid, "did:aithos:zCarol");
+        assert.equal(parsed.mandateId, "mandate:01H8ISSUER");
+        assert.equal(parsed.granteeId, "urn:aithos:agent:bob1");
+    });
     it("readDelegateBundleText accepts string passthrough", async () => {
         const text = delegateBundleText({
             mandateId: "m",

package/dist/test/canonical-conformance.test.d.ts

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

package/dist/test/canonical-conformance.test.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Safety gate for the canonicalization refactor.
+ *
+ * The SDK historically carried three hand-rolled copies of `jcsCanonicalize`
+ * (internal/envelope.ts, data.ts, apps.ts). data.ts uses it to canonicalize a
+ * record payload BEFORE encryption (it feeds the AAD/plaintext), so a single
+ * differing byte vs. the canonicalization used at decrypt/verify time would
+ * silently corrupt data. Before swapping those copies onto
+ * `@aithos/protocol-core`'s `canonicalize`, this test proves the two produce
+ * identical output across a representative corpus.
+ *
+ * Known, accepted divergence: lone UTF-16 surrogates. `JSON.stringify` escapes
+ * them (\uXXXX) whereas core emits the raw code unit. Lone surrogates never
+ * appear in Aithos payloads (record fields are well-formed JSON strings), so
+ * the corpus excludes them by design.
+ */
+import { describe, test } from "node:test";
+import { strict as assert } from "node:assert";
+import { canonicalize } from "@aithos/protocol-core/canonical";
+/** Exact copy of the SDK's legacy jcsCanonicalize (pre-refactor reference). */
+function jcsCanonicalize(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        throw new Error("Cannot canonicalize undefined");
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("non-finite number");
+        return value.toString();
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map(jcsCanonicalize).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return ("{" +
+            keys
+                .map((k) => JSON.stringify(k) + ":" + jcsCanonicalize(obj[k]))
+                .join(",") +
+            "}");
+    }
+    throw new Error(`Cannot canonicalize ${typeof value}`);
+}
+const corpus = [
+    null,
+    true,
+    false,
+    0,
+    -1,
+    42,
+    Number.MAX_SAFE_INTEGER,
+    "",
+    "hello",
+    "with \"quotes\" and \\ backslash",
+    "tab\tnewline\nreturn\rbackspace\bform\f",
+    "control
 end",
+    "accented éàùçö and emoji 😀🚀 and 漢字",
+    "slash / and at @ and unicode nbsp",
+    [],
+    [1, 2, 3],
+    ["z", "a", "m"],
+    [{ b: 1, a: 2 }, [3, [4, 5]]],
+    {},
+    { b: 2, a: 1, c: 3 },
+    { z: { y: { x: [1, "two", false, null] } } },
+    { "key with spaces": 1, "weird:char": 2, "": "empty key" },
+    { émoji: "😀", "漢字": 1, A: 0, a: 0 }, // mixed-case + non-ascii keys (UTF-16 order)
+    {
+        record: { name: "Aïko", tags: ["x", "y"], n: 7, active: true, meta: null },
+    },
+];
+describe("canonicalize conformance — core vs legacy SDK jcsCanonicalize", () => {
+    for (const [i, value] of corpus.entries()) {
+        test(`corpus[${i}] is byte-identical`, () => {
+            assert.equal(canonicalize(value), jcsCanonicalize(value));
+        });
+    }
+});
+//# sourceMappingURL=canonical-conformance.test.js.map

package/dist/test/compute-delegate-path.test.d.ts

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