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

package/dist/src/data.js

@@ -1,35 +1,42 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Mathieu Colla
 /**
- * `sdk.data` — high-level API for the Aithos data sub-protocol PDS.
+ * `sdk.data` — the Aithos data sub-protocol PDS as a plain database.
  *
- * The Aithos data sub-protocol stores operational records (contacts,
- * messages, ...) under a subject's identity, encrypted client-side,
- * accessible to authorized apps via signed mandates. This module is the
- * ergonomic façade developers consume:
+ * Records (contacts, prospects, messages, …) live under a subject's identity,
+ * encrypted client-side, sealed under the subject's dedicated **`#data`**
+ * sphere. A developer never chooses a sphere, never handles a key — the SDK
+ * derives everything from the session. There are exactly two ways in, both off
+ * the auth session:
  *
- *     const client = createDataClient({ pdsUrl, did, sphereSeed });
- *     const contacts = client.collection("contacts");
- *     const id = await contacts.insert({ name: "Jean", phone: "+33..." });
- *     const list = await contacts.list({ filter: { status: "lead" } });
+ *     // 1. As the OWNER (signed in) — your own database:
+ *     const db = auth.data;                 // === auth.ownerDataClient()
+ *     const id = await db.collection("contacts").insert({ name: "Jean" });
+ *     const leads = await db.collection("contacts").list({ filter: { status: "lead" } });
  *
- * Under the hood the module handles: envelope signing per spec §11,
- * CMK / DEK lifecycle (generate, wrap, unwrap), per-record AEAD
- * encryption, split between indexable metadata (server-visible) and
- * encrypted payload (server-blind), JSON-RPC dispatch.
+ *     // 2. As a DELEGATE (you imported a mandate) — the subject's database:
+ *     const db = auth.delegateDataClient();  // single active mandate; or { subjectDid }
+ *     await db.collection("prospects").insert({ ... });  // needs data.prospects.write
  *
- * It does not (yet) handle: mandate-delegate authentication on the
- * caller side (the SDK only signs as owner in v0.1), full schema
- * publication (no `registerSchema` RPC yet — that lands with A2b, cf.
- * aithos-protocol/PLAN-A2b-schema-self-registration.md), forward-secrecy
- * CMK rotation primitives. Those land in later Sub-jalons.
+ * `auth.data` returns whichever applies to how you connected, with an identical
+ * CRUD surface. Owner-only operations (createCollection, authorizeDelegate,
+ * registerSchema) belong to the owner and throw `-32042` on the delegate path:
+ * the owner holds the CMK and decides who may access the collection (a one-time
+ * onboarding step), then the delegate does record CRUD bounded by its scope.
  *
- * Apps that need to use a vendor schema (`aithos.x.<vendor>.<name>.v<N>`,
- * or any non-`aithos.*` namespace) pass their schema definitions to
- * `createDataClient({ schemas: [...] })`. The PDS accepts these at face
- * value (no server-side metadata validation pending A2b); the SDK uses
- * the supplied schema definitions to split records into indexable
- * metadata and encrypted payload.
+ * The low-level `createDataClient` / `createDelegateDataClient` (which take a
+ * raw seed) are NOT exported from the package — they exist only as internals of
+ * the session accessors above. This is deliberate: passing a seed by hand is
+ * exactly what let an app seal data under the wrong key.
+ *
+ * Under the hood the module handles: envelope signing per spec §11, CMK / DEK
+ * lifecycle (generate, wrap, unwrap), per-record AEAD encryption, the split
+ * between indexable metadata (server-visible) and encrypted payload
+ * (server-blind), and JSON-RPC dispatch.
+ *
+ * Vendor schemas (`aithos.x.<vendor>.<name>.v<N>`) are passed via the
+ * `{ schemas: [...] }` option on the session accessor; the SDK uses them to
+ * split records into indexable metadata and encrypted payload.
  *
  * Spec ref: spec/data/01..10 of the aithos-protocol repo.
  */
@@ -61,15 +68,20 @@ export function createDataClient(args) {
     return new DataClientImpl(args);
 }
 /**
- * Build a read-only data client that reads a subject's collections under
- * a mandate (delegate path). The returned {@link ReadonlyDataClient}
- * signs every request as the delegate (bare-multibase verificationMethod
- * + the mandate attached to the envelope), and decrypts records using the
- * CMK the owner re-wrapped for this delegate via
- * {@link DataClient.authorizeDelegate}.
+ * Build a data client that operates on a subject's collections under a
+ * mandate (delegate path). It signs every request as the delegate
+ * (bare-multibase verificationMethod + the mandate attached to the
+ * envelope) and decrypts/encrypts records using the CMK the owner
+ * re-wrapped for this delegate via {@link DataClient.authorizeDelegate}.
  *
- * Writes are not available on the returned type and throw `-32042` if
- * forced.
+ * Record CRUD is bounded by the mandate scope: reads need
+ * `data.<col>.read`, writes need `data.<col>.write` (or `.admin` /
+ * wildcard) — enforced client-side and by the PDS. Owner-only operations
+ * (createCollection, authorizeDelegate, revokeDelegate, registerSchema)
+ * always throw `-32042`: the owner holds the CMK and controls access.
+ *
+ * @internal Prefer the session accessor `auth.data` (owner) / the delegate
+ * session over hand-constructing this with a raw seed.
  */
 export function createDelegateDataClient(args) {
     const granteePubMb = args.granteePubkeyMultibase ??
@@ -171,14 +183,38 @@ class DataClientImpl {
             this.#deposit = args.deposit;
         this.#localSchemas = new Map((args.schemas ?? []).map((s) => [s.schema, s]));
     }
-    /** Throw a read-only error when a mutating verb is called on a delegate
-     * client. The PDS rejects these server-side too; this is the fast,
-     * local guard with a precise message. */
+    /** Owner-only operations: collection lifecycle (create/ensure), delegate
+     * management (authorize/revoke) and schema registration. A delegate — even
+     * with a write mandate — cannot perform these: the owner holds the CMK and
+     * controls who may access the collection. The PDS enforces the same. */
     #assertOwner(op) {
         if (this.#delegate) {
-            const e = new Error(`sdk.data: "${op}" is not permitted for a delegate client (read-only mandate). ` +
-                `A data.<collection>.read mandate grants get/list only; writes require the owner ` +
-                `or a data.<collection>.write mandate (not yet supported on the delegate path).`);
+            const e = new Error(`sdk.data: "${op}" is owner-only. A delegate (even with a write mandate) cannot ` +
+                `create collections, authorize/revoke delegates, or register schemas — the owner ` +
+                `holds the CMK and controls access. Record CRUD (insert/get/list/update/delete) ` +
+                `is available to a delegate whose mandate carries the matching scope.`);
+            e.code = -32042;
+            throw e;
+        }
+    }
+    /** Record-write guard. Owner: always allowed. Delegate: allowed iff the
+     * mandate carries a write/admin scope for this collection (data.<col>.write,
+     * data.*.write, data.<col>.admin, data.*.admin). The PDS enforces the same;
+     * this is the fast, precise local error. */
+    #assertCanWrite(op, collectionName) {
+        if (!this.#delegate)
+            return; // owner can always write
+        const scopes = this.#delegate.mandate.scopes ?? [];
+        const needed = [
+            `data.${collectionName}.write`,
+            `data.*.write`,
+            `data.${collectionName}.admin`,
+            `data.*.admin`,
+        ];
+        const ok = scopes.some((s) => needed.includes(s.split(".").slice(0, 3).join(".")));
+        if (!ok) {
+            const e = new Error(`sdk.data: "${op}" on "${collectionName}" requires a data.${collectionName}.write ` +
+                `(or .admin / wildcard) scope. This mandate grants: [${scopes.join(", ")}].`);
             e.code = -32042;
             throw e;
         }
@@ -431,7 +467,7 @@ class DataClientImpl {
         return state;
     }
     async _insert(state, record) {
-        this.#assertOwner("insert");
+        this.#assertCanWrite("insert", state.name);
         const cmk = this.#cmkCache.get(state.name);
         if (!cmk)
             throw new Error("CMK not loaded");
@@ -500,7 +536,7 @@ class DataClientImpl {
         };
     }
     async _update(state, recordId, record) {
-        this.#assertOwner("update");
+        this.#assertCanWrite("update", state.name);
         const cmk = this.#cmkCache.get(state.name);
         if (!cmk)
             throw new Error("CMK not loaded");
@@ -519,7 +555,7 @@ class DataClientImpl {
         });
     }
     async _delete(state, recordId) {
-        this.#assertOwner("delete");
+        this.#assertCanWrite("delete", state.name);
         await this.#call("/mcp/primitives/write", "aithos.data.delete_record", {
             collection_urn: state.urn,
             record_id: recordId,

package/dist/src/index.d.ts

@@ -1,12 +1,17 @@
-export declare const VERSION = "0.1.0-alpha.56";
+export declare const VERSION = "0.1.0-alpha.57";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 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, RunConversationArgs, RunConversationResult, ComputeWorkingSet, WorkingSetSection, ConverseToolCall, ConverseStopReason, 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, InvokeTurnArgs, InvokeTurnResult, RunConversationLocalArgs, RunConversationLocalResult, TranscribeModelId, TranscribeProgressState, TranscribeSegment, TranscribeWord, InvokeTranscribeArgs, InvokeTranscribeResult, PrepareTranscribeArgs, PrepareTranscribeResult, StartTranscribeArgs, StartTranscribeResult, TranscribeStatusResult, TranscribeJobSummary, } from "./compute.js";
 export { ComputeNamespace } from "./compute.js";
+export type { AgentMessage, AgentToolSpec, AgentTurnResult, ContentBlock, ToolCallTrace, LoopStopReason, DispatchOutcome, } from "./agent-loop.js";
+export { runAgenticLoopLocal } from "./agent-loop.js";
+export { AITHOS_AGENT_TOOLS, AITHOS_AGENT_READ_TOOLS, AITHOS_AGENT_WRITE_TOOLS, selectAgentTools, isWriteTool, } from "./agent-tools.js";
+export type { AgentDispatchContext, DataProvider } from "./agent-dispatch.js";
+export { dispatchAgentToolLocal } from "./agent-dispatch.js";
 export type { LocalPendingEntry, LocalPendingStatus, TranscribeDraftMeta, TranscribeDraftRecord, } from "./transcribe-resilience.js";
 export { LocalPendingTranscribeTracker, TranscribeDraftStore, TranscribeDraftUnavailableError, } from "./transcribe-resilience.js";
 export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, GetBalanceArgs, GetBalanceResult, } from "./wallet.js";
@@ -27,7 +32,7 @@ export type { AudienceSet, AppCreditPackId, CreateAppTopupSessionArgs, CreateApp
 export * as onboarding from "./onboarding.js";
 export { createBrowserIdentity, browserIdentityFromStored, type BrowserIdentity, } from "@aithos/protocol-client";
 export type { Section } from "@aithos/protocol-client";
-export { createDataClient, createDelegateDataClient, createAppendDataClient, type CreateDataClientArgs, type CreateDelegateDataClientArgs, type CreateAppendDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, type AppendOnlyDataClient, type AppendOnlyDataCollection, type ListOpts, type AithosSchemaLite, liteFromPublishedSchema, } from "./data.js";
+export { createAppendDataClient, type CreateAppendDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, type AppendOnlyDataClient, type AppendOnlyDataCollection, type ListOpts, type AithosSchemaLite, liteFromPublishedSchema, } from "./data.js";
 export { ensureDataSphere, rekeyLegacyCollections, addDataSphereWrap, migrateLegacyEthosToDataSphere, type MigrateOptions, type MigrateProgress, type EnsureDataSphereResult, type RekeyReport, type CollectionRekeyEntry, type CollectionRekeyStatus, type FullMigrationResult, } from "./migrate.js";
 export { buildSignedRotatedDidDocument, rotateEthos, type RotationSeeds, type DidDocumentLike, type RotateEthosOptions, type RotateEthosResult, } from "./rotate.js";
 export { createAssetsClient, AssetsClient, type CreateAssetsClientArgs, type AttachedContext, type AssetUploadInput, type AssetUploadResult, type AssetFetchResult, type AssetBrief, type ListAssetsOpts, type ThumbnailUploadInput, type ThumbnailUploadResult, type RecipientResolver, type RecipientSet, } from "./assets.js";

package/dist/src/index.js

@@ -17,7 +17,7 @@
 // Public types specific to the SDK (`AithosSDKConfig`, `AithosSDKError`)
 // are exported from here. Endpoint config (`AithosSdkEndpoints`,
 // `DEFAULT_SDK_ENDPOINTS`) likewise.
-export const VERSION = "0.1.0-alpha.56";
+export const VERSION = "0.1.0-alpha.57";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can
@@ -26,6 +26,9 @@ export { AithosSDKError } from "./types.js";
 export { AithosRpcError } from "@aithos/protocol-client";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export { ComputeNamespace } from "./compute.js";
+export { runAgenticLoopLocal } from "./agent-loop.js";
+export { AITHOS_AGENT_TOOLS, AITHOS_AGENT_READ_TOOLS, AITHOS_AGENT_WRITE_TOOLS, selectAgentTools, isWriteTool, } from "./agent-tools.js";
+export { dispatchAgentToolLocal } from "./agent-dispatch.js";
 export { LocalPendingTranscribeTracker, TranscribeDraftStore, TranscribeDraftUnavailableError, } from "./transcribe-resilience.js";
 export { WalletNamespace } from "./wallet.js";
 export { WebNamespace, WEB_EXTRACT_SCOPE } from "./web.js";
@@ -68,7 +71,14 @@ export { createBrowserIdentity, browserIdentityFromStored, } from "@aithos/proto
 // `sdk.data` namespace — Aithos data sub-protocol PDS client. Manages
 // the lifecycle of subject-owned, encrypted, schema-validated records.
 // See spec/data/ in the aithos-protocol repo.
-export { createDataClient, createDelegateDataClient, createAppendDataClient, 
+// The low-level `createDataClient` (owner) and `createDelegateDataClient`
+// (delegate) factories are intentionally NOT exported: they take a raw sphere
+// seed, which is exactly the footgun that let apps sign data ops with the wrong
+// key. Use the session instead — `auth.data` / `auth.ownerDataClient()` for the
+// owner (always `#data`), `auth.delegateDataClient()` for a mandate-bearing
+// delegate. The key/sphere is derived under the hood; the developer only ever
+// sees a database.
+export { createAppendDataClient, 
 // Derive an AithosSchemaLite from a published JSON Schema (vendor schemas the
 // client didn't bundle). The SDK uses this internally to auto-resolve unknown
 // collection schemas from the PDS; exported for apps that want it directly.

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

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

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/invoke-turn-sdk.test.d.ts

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