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

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

@@ -0,0 +1,18 @@
+import type { DispatchOutcome } from "./agent-loop.js";
+import type { EthosClient } from "./ethos.js";
+/** Optional structured-data reader (gamma). Wire `sdk.data` here if available. */
+export type DataProvider = (collection: string, limit: number) => Promise<readonly Record<string, unknown>[]>;
+export interface AgentDispatchContext {
+    /** Ethos client for the conversation's subject (resolved via ethos.of(did)). */
+    readonly ethos: EthosClient;
+    /** Scopes carried by the active delegate mandate. Empty/owner → see `mode`. */
+    readonly delegateScopes: readonly string[];
+    /** Optional gamma reader for `data_query`. Absent → tool returns is_error. */
+    readonly dataProvider?: DataProvider;
+}
+/**
+ * Execute one tool LOCALLY. Never throws on a tool-level problem — converts it
+ * into an `is_error` outcome the model can read and recover from.
+ */
+export declare function dispatchAgentToolLocal(ctx: AgentDispatchContext, name: string, input: Record<string, unknown>): Promise<DispatchOutcome>;
+//# sourceMappingURL=agent-dispatch.d.ts.map

package/dist/src/agent-dispatch.js

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+import { ZONE_NAMES } from "./ethos.js";
+import { AithosSDKError } from "./types.js";
+import { TOOL_ETHOS_LIST_SECTIONS, TOOL_ETHOS_READ_SECTION, TOOL_DATA_QUERY, TOOL_ETHOS_ADD_SECTION, TOOL_ETHOS_UPDATE_SECTION, TOOL_ETHOS_DELETE_SECTION, } from "./agent-tools.js";
+function ok(payload) {
+    return { payload: typeof payload === "string" ? payload : JSON.stringify(payload), isError: false };
+}
+function err(message) {
+    return { payload: JSON.stringify({ error: message }), isError: true };
+}
+/** Whether the caller may WRITE the given zone. */
+function canWriteZone(ctx, zone) {
+    if (ctx.ethos.mode === "owner")
+        return true;
+    if (ctx.ethos.mode === "anonymous")
+        return false;
+    return ctx.delegateScopes.includes(`ethos.write.${zone}`);
+}
+/**
+ * Read every zone the caller can see, returning the zone + its sections.
+ * Zones the caller cannot read (ungranted scope / undecryptable) are skipped
+ * silently — same bounding rule as `AithosSDK.buildWorkingSet`.
+ */
+async function readableZones(ctx) {
+    const out = [];
+    for (const zone of ZONE_NAMES) {
+        try {
+            const sections = await ctx.ethos.zone(zone).sections();
+            out.push({
+                zone,
+                sections: sections.map((s) => ({ id: s.id, title: s.title, body: s.body })),
+            });
+        }
+        catch (e) {
+            if (e instanceof AithosSDKError)
+                continue; // not granted / not decryptable
+            throw e;
+        }
+    }
+    return out;
+}
+/**
+ * Execute one tool LOCALLY. Never throws on a tool-level problem — converts it
+ * into an `is_error` outcome the model can read and recover from.
+ */
+export async function dispatchAgentToolLocal(ctx, name, input) {
+    try {
+        switch (name) {
+            /* ------------------------------- reads ------------------------------ */
+            case TOOL_ETHOS_LIST_SECTIONS: {
+                const zones = await readableZones(ctx);
+                const sections = zones.flatMap(({ zone, sections }) => sections.map((s) => ({ zone, id: s.id, title: s.title })));
+                return ok({ sections });
+            }
+            case TOOL_ETHOS_READ_SECTION: {
+                const sectionId = input.section_id;
+                if (typeof sectionId !== "string" || !sectionId) {
+                    return err("section_id (string) is required");
+                }
+                const zones = await readableZones(ctx);
+                for (const { zone, sections } of zones) {
+                    const found = sections.find((s) => s.id === sectionId);
+                    if (found) {
+                        return ok({ zone, title: found.title, body: found.body });
+                    }
+                }
+                return err(`no readable section with id '${sectionId}'`);
+            }
+            case TOOL_DATA_QUERY: {
+                const collection = input.collection;
+                if (typeof collection !== "string" || !collection) {
+                    return err("collection (string) is required");
+                }
+                if (!ctx.dataProvider) {
+                    return err("structured data (gamma) is not available in this session");
+                }
+                const limit = typeof input.limit === "number" && Number.isInteger(input.limit)
+                    ? Math.max(1, Math.min(100, input.limit))
+                    : 20;
+                const records = await ctx.dataProvider(collection, limit);
+                return ok({ collection, records });
+            }
+            /* ------------------------------ writes ------------------------------ */
+            case TOOL_ETHOS_ADD_SECTION: {
+                const zone = input.zone;
+                const title = input.title;
+                const body = input.body;
+                if (!isZone(zone))
+                    return err("zone must be one of public|circle|self");
+                if (typeof title !== "string" || !title)
+                    return err("title (string) is required");
+                if (typeof body !== "string")
+                    return err("body (string) is required");
+                if (!canWriteZone(ctx, zone)) {
+                    return err(`not authorized to write the '${zone}' zone (missing ethos.write.${zone})`);
+                }
+                ctx.ethos.zone(zone).addSection({ title, body });
+                const result = await ctx.ethos.publish();
+                return ok({ published: true, zone, editionHeight: result.editionHeight });
+            }
+            case TOOL_ETHOS_UPDATE_SECTION: {
+                const sectionId = input.section_id;
+                if (typeof sectionId !== "string" || !sectionId) {
+                    return err("section_id (string) is required");
+                }
+                const patch = {};
+                if (input.title !== undefined) {
+                    if (typeof input.title !== "string")
+                        return err("title must be a string");
+                    patch.title = input.title;
+                }
+                if (input.body !== undefined) {
+                    if (typeof input.body !== "string")
+                        return err("body must be a string");
+                    patch.body = input.body;
+                }
+                if (patch.title === undefined && patch.body === undefined) {
+                    return err("nothing to update: provide title and/or body");
+                }
+                const located = await locateSection(ctx, sectionId);
+                if (!located)
+                    return err(`no readable section with id '${sectionId}'`);
+                if (!canWriteZone(ctx, located)) {
+                    return err(`not authorized to write the '${located}' zone (missing ethos.write.${located})`);
+                }
+                ctx.ethos.zone(located).updateSection(sectionId, patch);
+                const result = await ctx.ethos.publish();
+                return ok({ published: true, zone: located, editionHeight: result.editionHeight });
+            }
+            case TOOL_ETHOS_DELETE_SECTION: {
+                const sectionId = input.section_id;
+                if (typeof sectionId !== "string" || !sectionId) {
+                    return err("section_id (string) is required");
+                }
+                const located = await locateSection(ctx, sectionId);
+                if (!located)
+                    return err(`no readable section with id '${sectionId}'`);
+                if (!canWriteZone(ctx, located)) {
+                    return err(`not authorized to write the '${located}' zone (missing ethos.write.${located})`);
+                }
+                ctx.ethos.zone(located).deleteSection(sectionId);
+                const result = await ctx.ethos.publish();
+                return ok({ published: true, zone: located, editionHeight: result.editionHeight });
+            }
+            default:
+                return err(`unknown tool '${name}'`);
+        }
+    }
+    catch (e) {
+        // Any failure (scope refusal inside publish(), network, decrypt, …) →
+        // is_error so the model can recover; we never let it break the loop.
+        const message = e instanceof AithosSDKError
+            ? `${e.code}: ${e.message}`
+            : e?.message ?? String(e);
+        return err(message);
+    }
+}
+function isZone(v) {
+    return v === "public" || v === "circle" || v === "self";
+}
+/** Find which readable zone holds the section id, or null. */
+async function locateSection(ctx, sectionId) {
+    for (const zone of ZONE_NAMES) {
+        try {
+            const sections = await ctx.ethos.zone(zone).sections();
+            if (sections.some((s) => s.id === sectionId))
+                return zone;
+        }
+        catch (e) {
+            if (e instanceof AithosSDKError)
+                continue;
+            throw e;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=agent-dispatch.js.map

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

@@ -0,0 +1,94 @@
+export interface TextBlock {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface ToolUseBlock {
+    readonly type: "tool_use";
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+}
+export interface ToolResultBlock {
+    readonly type: "tool_result";
+    readonly tool_use_id: string;
+    /** Stringified result payload (JSON or plain text). */
+    readonly content: string;
+    /** Set when the tool failed — lets the model recover instead of us failing. */
+    readonly is_error?: boolean;
+}
+export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | Record<string, unknown>;
+/** A message in the running conversation. `content` is a string or blocks. */
+export interface AgentMessage {
+    readonly role: "user" | "assistant";
+    readonly content: string | readonly ContentBlock[];
+}
+/** Anthropic tool definition (forwarded to the proxy in `tools`). */
+export interface AgentToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly input_schema: Record<string, unknown>;
+}
+export type AgentTurnStopReason = "end_turn" | "max_tokens" | "stop_sequence" | "tool_use";
+/** One per-turn result from the proxy (`aithos.compute_invoke_turn`). */
+export interface AgentTurnResult {
+    readonly content: readonly ContentBlock[];
+    readonly stopReason: AgentTurnStopReason;
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+    /** Microcredits charged for THIS turn (cumulative billing — HANDOFF §1). */
+    readonly creditsCharged?: number;
+    readonly walletBalance?: number;
+}
+/** Extract the tool_use blocks from a turn's content (in order). */
+export declare function extractToolUseBlocks(content: readonly ContentBlock[]): readonly ToolUseBlock[];
+/** Concatenate the text blocks of a turn into a single string. */
+export declare function extractText(content: readonly ContentBlock[]): string;
+/** Build a single tool_result block. */
+export declare function toolResult(toolUseId: string, payload: string, isError?: boolean): ToolResultBlock;
+/** Build the user message carrying one or more tool_result blocks. */
+export declare function buildToolResultMessage(results: readonly ToolResultBlock[]): AgentMessage;
+export type LoopStopReason = "end_turn" | "max_tokens" | "stop_sequence" | "max_iterations";
+export interface ToolCallTrace {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly turn: number;
+}
+export interface AggregateUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+export interface DispatchOutcome {
+    readonly payload: string;
+    readonly isError: boolean;
+}
+export interface LocalAgenticLoopResult {
+    readonly finalContent: string;
+    readonly stopReason: LoopStopReason;
+    /** Number of proxy turns performed (each is a billed call). */
+    readonly iterations: number;
+    readonly usage: AggregateUsage;
+    readonly toolCalls: readonly ToolCallTrace[];
+    /** Sum of per-turn `creditsCharged` (HANDOFF §1: per-turn cumulative billing). */
+    readonly creditsCharged: number;
+    /** Wallet balance reported by the LAST turn (0 if none reported). */
+    readonly walletBalance: number;
+}
+export interface LocalAgenticLoopArgs {
+    /** Initial conversation (copied internally; not mutated by the caller). */
+    readonly messages: readonly AgentMessage[];
+    /** Hard cap on proxy turns. */
+    readonly maxIterations: number;
+    /** One signed proxy turn. Receives the running message list. */
+    readonly invokeTurn: (messages: readonly AgentMessage[]) => Promise<AgentTurnResult>;
+    /** Execute one tool call LOCALLY (read/write the user's ethos). Async. */
+    readonly dispatch: (name: string, input: Record<string, unknown>) => Promise<DispatchOutcome>;
+}
+/**
+ * Run the client-side agentic loop. Never throws on tool errors (they become
+ * `tool_result.is_error` so the model can recover); only `invokeTurn`
+ * rejections propagate to the caller (the proxy already refunded that turn).
+ */
+export declare function runAgenticLoopLocal(args: LocalAgenticLoopArgs): Promise<LocalAgenticLoopResult>;
+//# sourceMappingURL=agent-loop.d.ts.map

package/dist/src/agent-loop.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/* -------------------------------------------------------------------------- */
+/*  Pure helpers                                                              */
+/* -------------------------------------------------------------------------- */
+/** Extract the tool_use blocks from a turn's content (in order). */
+export function extractToolUseBlocks(content) {
+    return content.filter((b) => typeof b === "object" &&
+        b !== null &&
+        b.type === "tool_use");
+}
+/** Concatenate the text blocks of a turn into a single string. */
+export function extractText(content) {
+    return content
+        .filter((b) => typeof b === "object" &&
+        b !== null &&
+        b.type === "text" &&
+        typeof b.text === "string")
+        .map((b) => b.text)
+        .join("");
+}
+/** Build a single tool_result block. */
+export function toolResult(toolUseId, payload, isError = false) {
+    return {
+        type: "tool_result",
+        tool_use_id: toolUseId,
+        content: payload,
+        ...(isError ? { is_error: true } : {}),
+    };
+}
+/** Build the user message carrying one or more tool_result blocks. */
+export function buildToolResultMessage(results) {
+    return { role: "user", content: results };
+}
+/**
+ * Run the client-side agentic loop. Never throws on tool errors (they become
+ * `tool_result.is_error` so the model can recover); only `invokeTurn`
+ * rejections propagate to the caller (the proxy already refunded that turn).
+ */
+export async function runAgenticLoopLocal(args) {
+    const messages = [...args.messages];
+    const trace = [];
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let creditsCharged = 0;
+    let walletBalance = 0;
+    let lastText = "";
+    const usage = () => ({ inputTokens, outputTokens });
+    for (let turn = 1; turn <= args.maxIterations; turn++) {
+        const r = await args.invokeTurn(messages);
+        inputTokens += r.usage.inputTokens;
+        outputTokens += r.usage.outputTokens;
+        if (typeof r.creditsCharged === "number")
+            creditsCharged += r.creditsCharged;
+        if (typeof r.walletBalance === "number")
+            walletBalance = r.walletBalance;
+        const text = extractText(r.content);
+        if (text)
+            lastText = text;
+        const toolUses = extractToolUseBlocks(r.content);
+        // Terminal: the model stopped without (valid) tool calls.
+        if (r.stopReason !== "tool_use" || toolUses.length === 0) {
+            return {
+                finalContent: text || lastText,
+                stopReason: r.stopReason === "tool_use" ? "end_turn" : r.stopReason,
+                iterations: turn,
+                usage: usage(),
+                toolCalls: trace,
+                creditsCharged,
+                walletBalance,
+            };
+        }
+        // Append the assistant turn (carries the tool_use blocks), then dispatch
+        // each tool LOCALLY and feed the results back as a single user turn.
+        messages.push({ role: "assistant", content: r.content });
+        const results = [];
+        for (const tu of toolUses) {
+            const out = await args.dispatch(tu.name, tu.input);
+            trace.push({ name: tu.name, ok: !out.isError, turn });
+            results.push(toolResult(tu.id, out.payload, out.isError));
+        }
+        messages.push(buildToolResultMessage(results));
+    }
+    // Cap reached while still mid-tool-loop: return the last text we saw.
+    return {
+        finalContent: lastText,
+        stopReason: "max_iterations",
+        iterations: args.maxIterations,
+        usage: usage(),
+        toolCalls: trace,
+        creditsCharged,
+        walletBalance,
+    };
+}
+//# sourceMappingURL=agent-loop.js.map

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

@@ -0,0 +1,24 @@
+import type { AgentToolSpec } from "./agent-loop.js";
+export declare const TOOL_ETHOS_LIST_SECTIONS = "ethos_list_sections";
+export declare const TOOL_ETHOS_READ_SECTION = "ethos_read_section";
+export declare const TOOL_DATA_QUERY = "data_query";
+export declare const TOOL_ETHOS_ADD_SECTION = "ethos_add_section";
+export declare const TOOL_ETHOS_UPDATE_SECTION = "ethos_update_section";
+export declare const TOOL_ETHOS_DELETE_SECTION = "ethos_delete_section";
+export declare const AITHOS_AGENT_READ_TOOLS: readonly AgentToolSpec[];
+export declare const AITHOS_AGENT_WRITE_TOOLS: readonly AgentToolSpec[];
+export declare const AITHOS_AGENT_TOOLS: readonly AgentToolSpec[];
+export declare function isWriteTool(name: string): boolean;
+/**
+ * Resolve the tool specs to forward to the proxy.
+ *
+ * - `undefined` / empty → the full catalogue (read + write).
+ * - a list of names → exactly those (unknown names ignored).
+ * - `{ readOnly: true }` → only the read family (a caller that wants a
+ *   strictly non-mutating agent).
+ */
+export declare function selectAgentTools(opts?: {
+    readonly tools?: readonly string[];
+    readonly readOnly?: boolean;
+}): readonly AgentToolSpec[];
+//# sourceMappingURL=agent-tools.d.ts.map

package/dist/src/agent-tools.js

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/* ----------------------------------- read ---------------------------------- */
+export const TOOL_ETHOS_LIST_SECTIONS = "ethos_list_sections";
+export const TOOL_ETHOS_READ_SECTION = "ethos_read_section";
+export const TOOL_DATA_QUERY = "data_query";
+/* ---------------------------------- write ---------------------------------- */
+export const TOOL_ETHOS_ADD_SECTION = "ethos_add_section";
+export const TOOL_ETHOS_UPDATE_SECTION = "ethos_update_section";
+export const TOOL_ETHOS_DELETE_SECTION = "ethos_delete_section";
+/** The ethos zones a section can live in. */
+const ZONE_ENUM = ["public", "circle", "self"];
+export const AITHOS_AGENT_READ_TOOLS = [
+    {
+        name: TOOL_ETHOS_LIST_SECTIONS,
+        description: "Liste les sections disponibles de l'ethos de l'utilisateur (zone, id, " +
+            "titre), SANS leur contenu. À appeler en premier pour découvrir ce qui " +
+            "est lisible, puis utiliser ethos_read_section pour obtenir le détail.",
+        input_schema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: TOOL_ETHOS_READ_SECTION,
+        description: "Renvoie le contenu (titre + corps) d'une section de l'ethos, " +
+            "identifiée par son id obtenu via ethos_list_sections.",
+        input_schema: {
+            type: "object",
+            properties: {
+                section_id: { type: "string", description: "id de la section à lire" },
+            },
+            required: ["section_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: TOOL_DATA_QUERY,
+        description: "Renvoie les enregistrements d'une collection de données structurées " +
+            "de l'utilisateur (zone gamma).",
+        input_schema: {
+            type: "object",
+            properties: {
+                collection: { type: "string", description: "nom de la collection" },
+                limit: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 100,
+                    description: "nombre maximum d'enregistrements (défaut 20)",
+                },
+            },
+            required: ["collection"],
+            additionalProperties: false,
+        },
+    },
+];
+export const AITHOS_AGENT_WRITE_TOOLS = [
+    {
+        name: TOOL_ETHOS_ADD_SECTION,
+        description: "Ajoute une NOUVELLE section à l'ethos de l'utilisateur dans la zone " +
+            "indiquée. À n'utiliser que si l'information n'existe pas déjà (vérifier " +
+            "avec ethos_list_sections d'abord pour éviter les doublons). La " +
+            "modification est signée et publiée localement avec les clés de " +
+            "l'utilisateur.",
+        input_schema: {
+            type: "object",
+            properties: {
+                zone: {
+                    type: "string",
+                    enum: [...ZONE_ENUM],
+                    description: "zone de l'ethos : 'public' (visible de tous), 'circle' (cercle " +
+                        "de confiance), 'self' (privé). Choisir selon la sensibilité.",
+                },
+                title: { type: "string", description: "titre de la section" },
+                body: { type: "string", description: "contenu (texte) de la section" },
+            },
+            required: ["zone", "title", "body"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: TOOL_ETHOS_UPDATE_SECTION,
+        description: "Met à jour une section existante de l'ethos (titre et/ou corps), " +
+            "identifiée par son id (obtenu via ethos_list_sections). Ne modifier " +
+            "que ce qui doit changer.",
+        input_schema: {
+            type: "object",
+            properties: {
+                section_id: {
+                    type: "string",
+                    description: "id de la section à modifier",
+                },
+                title: { type: "string", description: "nouveau titre (optionnel)" },
+                body: { type: "string", description: "nouveau corps (optionnel)" },
+            },
+            required: ["section_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: TOOL_ETHOS_DELETE_SECTION,
+        description: "Supprime une section de l'ethos, identifiée par son id. Action " +
+            "irréversible une fois publiée — n'utiliser que si la suppression est " +
+            "explicitement justifiée.",
+        input_schema: {
+            type: "object",
+            properties: {
+                section_id: {
+                    type: "string",
+                    description: "id de la section à supprimer",
+                },
+            },
+            required: ["section_id"],
+            additionalProperties: false,
+        },
+    },
+];
+export const AITHOS_AGENT_TOOLS = [
+    ...AITHOS_AGENT_READ_TOOLS,
+    ...AITHOS_AGENT_WRITE_TOOLS,
+];
+const TOOL_BY_NAME = new Map(AITHOS_AGENT_TOOLS.map((t) => [t.name, t]));
+export function isWriteTool(name) {
+    return (name === TOOL_ETHOS_ADD_SECTION ||
+        name === TOOL_ETHOS_UPDATE_SECTION ||
+        name === TOOL_ETHOS_DELETE_SECTION);
+}
+/**
+ * Resolve the tool specs to forward to the proxy.
+ *
+ * - `undefined` / empty → the full catalogue (read + write).
+ * - a list of names → exactly those (unknown names ignored).
+ * - `{ readOnly: true }` → only the read family (a caller that wants a
+ *   strictly non-mutating agent).
+ */
+export function selectAgentTools(opts) {
+    if (opts?.readOnly)
+        return AITHOS_AGENT_READ_TOOLS;
+    const requested = opts?.tools;
+    if (!requested || requested.length === 0)
+        return AITHOS_AGENT_TOOLS;
+    const out = [];
+    for (const name of requested) {
+        const spec = TOOL_BY_NAME.get(name);
+        if (spec)
+            out.push(spec);
+    }
+    return out;
+}
+//# sourceMappingURL=agent-tools.js.map

package/dist/src/auth.d.ts

@@ -3,6 +3,7 @@ import { type AithosKeyStore } from "./key-store.js";
 import { DelegateActor } from "./internal/delegate-state.js";
 import { type SignedEnvelope } from "./internal/envelope.js";
 import { OwnerSigners } from "./internal/owner-signers.js";
+import { type DataClient, type AithosSchemaLite } from "./data.js";
 /** Default URL of the Aithos auth backend. */
 export declare const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
 /** Default URL of the Aithos primitives API (publish_identity, publish_ethos_edition, etc.). */
@@ -436,6 +437,64 @@ export declare class AithosAuth {
      * @internal
      */
     _getOwnerSigners(): OwnerSigners | null;
+    /**
+     * Ready-made owner data client bound to the signed-in account, signing +
+     * sealing under the dedicated **`#data`** sphere (the protocol-intended owner
+     * data key). This is the one-liner apps should use instead of hand-rolling
+     * `createDataClient` with a raw seed — hand-rolling with `#root` is exactly
+     * what left legacy collections sealed to the wrong key.
+     *
+     *   const data = auth.ownerDataClient({ schemas: [myVendorLite] });
+     *   await data.collection("notes").insert({ ... });   // owned under #data
+     *
+     * Throws when no owner is signed in, or when the account has no `#data`
+     * sphere (legacy accounts created before #data, or imported from a 4-seed
+     * recovery). Add one first with `rotateEthos` / the migration scripts, then
+     * re-import the resulting recovery — the error message says so.
+     *
+     * @param args.pdsUrl  PDS base URL. Defaults to the SDK default (pds.aithos.be).
+     * @param args.schemas Vendor `AithosSchemaLite` definitions to register for
+     *   WRITES (reads auto-resolve published schemas from the PDS).
+     */
+    ownerDataClient(args?: {
+        readonly pdsUrl?: string;
+        readonly schemas?: readonly AithosSchemaLite[];
+    }): DataClient;
+    /**
+     * Ready-made DELEGATE data client, bound to a mandate held in this session
+     * (imported via `importMandate` / an accepted invite). Same record-CRUD
+     * surface as the owner client, bounded by the mandate's scope — you never
+     * pass a key, a sphere, or the mandate itself to the data calls.
+     *
+     *   const db = auth.delegateDataClient();            // single active mandate
+     *   await db.collection("prospects").insert({ ... }); // needs data.prospects.write
+     *
+     * With several active mandates, pass `{ subjectDid }` or `{ mandateId }`.
+     * Owner-only ops (createCollection, authorizeDelegate, …) throw -32042 — the
+     * owner does those once, at onboarding.
+     */
+    delegateDataClient(args?: {
+        readonly subjectDid?: string;
+        readonly mandateId?: string;
+        readonly pdsUrl?: string;
+        readonly schemas?: readonly AithosSchemaLite[];
+    }): DataClient;
+    /**
+     * Unified data accessor — the database for "however you connected":
+     *   - signed in as owner            → your own collections under `#data`;
+     *   - acting under an imported mandate → the subject's collections (per scope).
+     *
+     * Identical CRUD surface either way; the developer never sees a sphere, a
+     * key, or the mandate. The mode follows how you authenticated, not a flag on
+     * the data calls.
+     *
+     *   const db = auth.data;
+     *   await db.collection("prospects").insert({ ... });
+     *
+     * Only ambiguous when you are BOTH signed in as owner AND holding mandates;
+     * then call `ownerDataClient()` / `delegateDataClient({ … })` explicitly.
+     */
+    get data(): DataClient;
     /**
      * Internal accessor — looks up an active delegate by mandate id.
      * @internal