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

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/endpoints.d.ts

@@ -33,9 +33,27 @@ export interface AithosSdkEndpoints {
      * `createAssetsClient`. Override for self-hosting or staging.
      */
     readonly assets: string;
+    /**
+     * Protocol API base URL (ethos reads/writes — `get_ethos_manifest`,
+     * `get_ethos_section`, `publish_ethos_edition`). Default `https://api.aithos.be`.
+     * Reached through `@aithos/protocol-client`; the SDK propagates this to the
+     * client via `configureEndpoints` on construction.
+     */
+    readonly api: string;
+    /**
+     * CDN base URL for immutable signed editions / DID documents. Default
+     * `https://cdn.aithos.be`. Also propagated to protocol-client.
+     */
+    readonly cdn: string;
 }
 /** Production defaults. */
 export declare const DEFAULT_SDK_ENDPOINTS: AithosSdkEndpoints;
+/**
+ * Dev-account preset — every endpoint on the isolated `*.dev.aithos.be` infra.
+ * Pass to the SDK as `new AithosSDK({ ..., endpoints: DEV_SDK_ENDPOINTS })` to
+ * point an app at the dev account (api/cdn flow to protocol-client too).
+ */
+export declare const DEV_SDK_ENDPOINTS: AithosSdkEndpoints;
 /** Compose the full compute-invoke URL: `${compute}/v1/invoke`. */
 export declare function computeInvokeUrl(endpoints: AithosSdkEndpoints): string;
 /** Compose the full web-extract URL: `${web}/v1/invoke`. */

package/dist/src/endpoints.js

@@ -7,6 +7,22 @@ export const DEFAULT_SDK_ENDPOINTS = {
     web: "https://extract.aithos.be",
     pds: "https://pds.aithos.be",
     assets: "https://assets.aithos.be",
+    api: "https://api.aithos.be",
+    cdn: "https://cdn.aithos.be",
+};
+/**
+ * Dev-account preset — every endpoint on the isolated `*.dev.aithos.be` infra.
+ * Pass to the SDK as `new AithosSDK({ ..., endpoints: DEV_SDK_ENDPOINTS })` to
+ * point an app at the dev account (api/cdn flow to protocol-client too).
+ */
+export const DEV_SDK_ENDPOINTS = {
+    compute: "https://compute.dev.aithos.be",
+    wallet: "https://wallet.dev.aithos.be",
+    web: "https://extract.dev.aithos.be",
+    pds: "https://pds.dev.aithos.be",
+    assets: "https://assets.dev.aithos.be",
+    api: "https://api.dev.aithos.be",
+    cdn: "https://cdn.dev.aithos.be",
 };
 /** Compose the full compute-invoke URL: `${compute}/v1/invoke`. */
 export function computeInvokeUrl(endpoints) {

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 { DEFAULT_SDK_ENDPOINTS, DEV_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, 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,15 +17,18 @@
 // 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
 // `instanceof`-check server-side errors and inspect the JSON-RPC code
 // without taking a direct dependency on @aithos/protocol-client.
 export { AithosRpcError } from "@aithos/protocol-client";
-export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
+export { DEFAULT_SDK_ENDPOINTS, DEV_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/src/sdk.js

@@ -3,6 +3,7 @@
 import { AppsNamespace } from "./apps.js";
 import { ComputeNamespace, } from "./compute.js";
 import { resolveEndpoints } from "./endpoints.js";
+import { configureEndpoints as configureProtocolClientEndpoints } from "@aithos/protocol-client";
 import { EthosNamespace } from "./ethos.js";
 import { MandatesNamespace } from "./mandates.js";
 import { AithosSDKError } from "./types.js";
@@ -41,6 +42,10 @@ export class AithosSDK {
         this.endpoints = resolveEndpoints(config.endpoints);
         this.appDid = config.appDid;
         this.auth = config.auth;
+        // Ethos reads/writes flow through @aithos/protocol-client, which keeps its
+        // own (module-scoped) api/cdn config. Propagate ours so that pointing the
+        // SDK at a dev account (endpoints.api/cdn) also redirects the ethos calls.
+        configureProtocolClientEndpoints({ api: this.endpoints.api, cdn: this.endpoints.cdn });
         const fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
         this.compute = new ComputeNamespace({
             auth: config.auth,

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