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

package/dist/src/auth.js

@@ -28,6 +28,9 @@ import { parseDelegateBundle, readDelegateBundleText, } from "./internal/delegat
 import { DelegateActor, DelegateRegistry, } from "./internal/delegate-state.js";
 import { signOwnerEnvelope, } from "./internal/envelope.js";
 import { OwnerSigners } from "./internal/owner-signers.js";
+import { createDataClient, createDelegateDataClient, } from "./data.js";
+import { delegateKeyPair } from "./internal/protocol-client-bridge.js";
+import { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 import { parseRecoveryFile, readRecoveryFileText, serializeRecoveryFile, } from "./internal/recovery-file.js";
 import { AithosSDKError } from "./types.js";
 /** Default URL of the Aithos auth backend. */
@@ -221,6 +224,118 @@ export class AithosAuth {
     _getOwnerSigners() {
         return this.#ownerSigners;
     }
+    /**
+     * 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 = {}) {
+        if (!this.#ownerSigners || this.#ownerSigners.destroyed) {
+            throw new AithosSDKError("auth_not_signed_in", "ownerDataClient: no owner is signed in. Call signIn / signUp / signInCustodial first.");
+        }
+        const stored = this.#ownerSigners._unsafeStoredIdentity();
+        if (!stored.seeds.data) {
+            throw new AithosSDKError("auth_no_data_sphere", "ownerDataClient: this account has no #data sphere, so it cannot own collections under " +
+                "the #data convention. New accounts get one at sign-up; a legacy account (or a 4-seed " +
+                "recovery) must add it first via rotateEthos / the migration scripts, then re-import the " +
+                "resulting recovery (which carries the #data seed).");
+        }
+        return createDataClient({
+            pdsUrl: args.pdsUrl ?? DEFAULT_SDK_ENDPOINTS.pds,
+            did: stored.did,
+            sphereSeed: hexToBytesLocal(stored.seeds.data),
+            verificationMethod: `${stored.did}#data`,
+            ...(args.schemas ? { schemas: args.schemas } : {}),
+            fetch: this.#fetchImpl,
+        });
+    }
+    /**
+     * 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 = {}) {
+        let actor;
+        if (args.mandateId) {
+            actor = this.#delegates.get(args.mandateId);
+        }
+        else if (args.subjectDid) {
+            actor = this.#delegates.findForSubject(args.subjectDid);
+        }
+        else {
+            const all = this.#delegates.list();
+            if (all.length === 1) {
+                actor = all[0];
+            }
+            else if (all.length === 0) {
+                throw new AithosSDKError("auth_no_delegate", "delegateDataClient: no mandate imported in this session. Call importMandate / accept an invite first.");
+            }
+            else {
+                throw new AithosSDKError("auth_ambiguous_delegate", `delegateDataClient: ${all.length} mandates are active — pass { subjectDid } or { mandateId } to choose one.`);
+            }
+        }
+        if (!actor || actor.destroyed) {
+            throw new AithosSDKError("auth_no_delegate", "delegateDataClient: the requested mandate is not active in this session.");
+        }
+        return createDelegateDataClient({
+            pdsUrl: args.pdsUrl ?? DEFAULT_SDK_ENDPOINTS.pds,
+            subjectDid: actor.subjectDid,
+            mandate: actor.mandate,
+            delegateSeed: delegateKeyPair(actor).seed,
+            granteePubkeyMultibase: actor.granteePubkeyMultibase,
+            ...(args.schemas ? { schemas: args.schemas } : {}),
+            fetch: this.#fetchImpl,
+        });
+    }
+    /**
+     * 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() {
+        const ownerActive = !!this.#ownerSigners && !this.#ownerSigners.destroyed;
+        const delegateCount = this.#delegates.list().length;
+        if (ownerActive && delegateCount === 0)
+            return this.ownerDataClient();
+        if (!ownerActive && delegateCount >= 1)
+            return this.delegateDataClient();
+        if (ownerActive && delegateCount >= 1) {
+            throw new AithosSDKError("auth_data_ambiguous", "auth.data: both an owner and delegate mandate(s) are active. Use ownerDataClient() or delegateDataClient({ … }) explicitly.");
+        }
+        throw new AithosSDKError("auth_not_signed_in", "auth.data: no owner signed in and no mandate imported. Call signIn / signUp or importMandate first.");
+    }
     /**
      * Internal accessor — looks up an active delegate by mandate id.
      * @internal
@@ -1445,6 +1560,12 @@ function bytesToHex(b) {
         out += b[i].toString(16).padStart(2, "0");
     return out;
 }
+function hexToBytesLocal(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.substr(i * 2, 2), 16);
+    return out;
+}
 /**
  * Split a custodial seed bundle into the keystore's hex seeds, zeroizing the
  * raw bytes (the bundle and every slice) before returning.

package/dist/src/compute.d.ts

@@ -1,6 +1,8 @@
 import type { AithosAuth } from "./auth.js";
 import { type AithosSdkEndpoints } from "./endpoints.js";
 import { type LocalPendingEntry, type TranscribeDraftMeta, type TranscribeDraftRecord } from "./transcribe-resilience.js";
+import { type AgentMessage, type AgentToolSpec, type AgentTurnStopReason, type ContentBlock, type LoopStopReason, type ToolCallTrace } from "./agent-loop.js";
+import { type DataProvider } from "./agent-dispatch.js";
 export interface ComputeMessage {
     readonly role: "user" | "assistant";
     readonly content: string;
@@ -173,6 +175,81 @@ export interface RunConversationResult {
     readonly receiptId?: string;
     readonly sponsoredBy?: string;
 }
+export interface InvokeTurnArgs {
+    /** Mandate id — optional for owner sessions, required for delegate sessions. */
+    readonly mandateId?: string;
+    readonly model: string;
+    /** Running conversation. `content` may be a string OR Anthropic blocks. */
+    readonly messages: readonly AgentMessage[];
+    /** Anthropic tool specs to expose this turn. */
+    readonly tools: readonly AgentToolSpec[];
+    readonly system?: string;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface InvokeTurnResult {
+    /** Raw content blocks (text + tool_use) — the caller detects tool calls. */
+    readonly content: readonly ContentBlock[];
+    readonly stopReason: AgentTurnStopReason;
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+    /** Microcredits charged for THIS single turn. */
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+    readonly fundedBy?: "sponsored" | "grant" | "purchase";
+    readonly receiptId?: string;
+    readonly sponsoredBy?: string;
+}
+export interface RunConversationLocalArgs {
+    /** Mandate id — optional for owner sessions, required for delegate sessions. */
+    readonly mandateId?: string;
+    /**
+     * Subject DID whose ethos the agent reads/writes. Defaults to the signed-in
+     * owner, or (delegate session) the mandate's subject.
+     */
+    readonly subjectDid?: string;
+    readonly model: string;
+    /** Initial conversation (plain string turns). */
+    readonly messages: readonly ComputeMessage[];
+    readonly system?: string;
+    /**
+     * Subset of Aithos tool names to expose. Omit for the full catalogue
+     * (read + write). Ignored when `readOnly` is set.
+     */
+    readonly tools?: readonly string[];
+    /** Expose only the read family (no mutations). */
+    readonly readOnly?: boolean;
+    /** Cap on proxy turns (each is a billed call). Default 6, hard max 12. */
+    readonly maxIterations?: number;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    /** Optional gamma reader powering `data_query`. Absent → that tool errors. */
+    readonly dataProvider?: DataProvider;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface RunConversationLocalResult {
+    readonly content: string;
+    readonly stopReason: LoopStopReason;
+    readonly iterations: number;
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+    readonly toolCalls: readonly ToolCallTrace[];
+    /** Sum of per-turn charges (HANDOFF §1: per-turn cumulative billing). */
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    /** Audit id of the LAST turn. */
+    readonly auditId: string;
+    readonly fundedBy?: "sponsored" | "grant" | "purchase";
+    readonly receiptId?: string;
+}
 /**
  * Stable cross-provider image model ids supported by the Aithos compute
  * proxy. New models can be added on the server side without an SDK
@@ -497,6 +574,41 @@ export declare class ComputeNamespace {
      *   `mandate_revoked`, `insufficient_credits`, …).
      */
     runConversation(args: RunConversationArgs): Promise<RunConversationResult>;
+    /**
+     * Run ONE Bedrock turn with tool-calling through the proxy
+     * (`aithos.compute_invoke_turn`). Returns the raw content blocks — including
+     * any `tool_use` — so the caller can dispatch tools and loop. This is the
+     * per-turn primitive the CLIENT-SIDE agentic loop is built on; most callers
+     * want {@link runConversationLocal} instead, which drives the loop and
+     * dispatches Aithos tools locally.
+     *
+     * Same signer paths and billing as {@link invokeBedrock}; billed once per
+     * turn.
+     */
+    invokeTurn(args: InvokeTurnArgs): Promise<InvokeTurnResult>;
+    /**
+     * Run a CLIENT-SIDE agentic conversation with tool-calling: a multi-turn
+     * loop where each turn is one signed proxy call ({@link invokeTurn}) and the
+     * tools the model requests are dispatched LOCALLY against the user's own
+     * ethos (reads decrypt locally; writes stage + sign + publish locally). The
+     * proxy does pure per-turn inference and never holds a decryption key — keys,
+     * data, and dispatch all stay on the client (HANDOFF-AGENT-WRITE-MODE.md
+     * §1/§3).
+     *
+     * Authorisation: an owner has full authority over their own ethos; a
+     * delegate is bounded by the mandate's `ethos.read.*` / `ethos.write.*`
+     * scopes (a tool out of scope returns an error to the model — nothing is
+     * published). The spend capability (`compute.invoke`) is checked server-side
+     * on every turn.
+     *
+     * Billing is PER-TURN cumulative: each turn is billed once and the result's
+     * `creditsCharged` is the sum across turns.
+     *
+     * @throws {AithosSDKError} `sdk_no_signer`, `sdk_no_delegate_for_mandate`,
+     *   `network`, `http`, `empty`, or any proxy code. Tool-level failures do
+     *   NOT throw — they are fed back to the model as errors.
+     */
+    runConversationLocal(args: RunConversationLocalArgs): Promise<RunConversationLocalResult>;
     /**
      * Multimodal Bedrock invoke — image + text → text response.
      * Default model: `claude-sonnet-4-6` (vision-capable, reliable JSON).

package/dist/src/compute.js

@@ -21,6 +21,13 @@ import { computeInvokeUrl, } from "./endpoints.js";
 import { delegateKeyPair, ownerKeyPair, } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
 import { LocalPendingTranscribeTracker, TranscribeDraftStore, } from "./transcribe-resilience.js";
+import { runAgenticLoopLocal, } from "./agent-loop.js";
+import { selectAgentTools } from "./agent-tools.js";
+import { dispatchAgentToolLocal, } from "./agent-dispatch.js";
+import { EthosNamespace } from "./ethos.js";
+/** Default / hard cap on client-side loop iterations (mirrors the proxy). */
+const DEFAULT_LOCAL_MAX_ITERATIONS = 6;
+const HARD_LOCAL_MAX_ITERATIONS = 12;
 /**
  * `sdk.compute` namespace. Constructed once by the {@link AithosSDK}
  * constructor; reads the active owner from the supplied
@@ -148,6 +155,134 @@ export class ComputeNamespace {
             signal: args.signal,
         });
     }
+    /**
+     * Run ONE Bedrock turn with tool-calling through the proxy
+     * (`aithos.compute_invoke_turn`). Returns the raw content blocks — including
+     * any `tool_use` — so the caller can dispatch tools and loop. This is the
+     * per-turn primitive the CLIENT-SIDE agentic loop is built on; most callers
+     * want {@link runConversationLocal} instead, which drives the loop and
+     * dispatches Aithos tools locally.
+     *
+     * Same signer paths and billing as {@link invokeBedrock}; billed once per
+     * turn.
+     */
+    async invokeTurn(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            model: args.model,
+            messages: args.messages,
+            tools: args.tools,
+            idempotency_key: idempotencyKey,
+        };
+        if (args.system !== undefined)
+            params.system = args.system;
+        if (args.maxTokens !== undefined)
+            params.max_tokens = args.maxTokens;
+        if (args.temperature !== undefined)
+            params.temperature = args.temperature;
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_invoke_turn",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /**
+     * Run a CLIENT-SIDE agentic conversation with tool-calling: a multi-turn
+     * loop where each turn is one signed proxy call ({@link invokeTurn}) and the
+     * tools the model requests are dispatched LOCALLY against the user's own
+     * ethos (reads decrypt locally; writes stage + sign + publish locally). The
+     * proxy does pure per-turn inference and never holds a decryption key — keys,
+     * data, and dispatch all stay on the client (HANDOFF-AGENT-WRITE-MODE.md
+     * §1/§3).
+     *
+     * Authorisation: an owner has full authority over their own ethos; a
+     * delegate is bounded by the mandate's `ethos.read.*` / `ethos.write.*`
+     * scopes (a tool out of scope returns an error to the model — nothing is
+     * published). The spend capability (`compute.invoke`) is checked server-side
+     * on every turn.
+     *
+     * Billing is PER-TURN cumulative: each turn is billed once and the result's
+     * `creditsCharged` is the sum across turns.
+     *
+     * @throws {AithosSDKError} `sdk_no_signer`, `sdk_no_delegate_for_mandate`,
+     *   `network`, `http`, `empty`, or any proxy code. Tool-level failures do
+     *   NOT throw — they are fed back to the model as errors.
+     */
+    async runConversationLocal(args) {
+        // Resolve the subject whose ethos the agent operates on.
+        const subjectDid = this.#resolveSubjectDid(args.subjectDid, args.mandateId);
+        // Resolve the ethos client + the delegate scopes that bound writes.
+        const ethosNs = this.#ethosNamespace();
+        const ethosClient = await ethosNs.of(subjectDid);
+        const delegateScopes = ethosClient.mode === "delegate"
+            ? this.#delegateScopesForSubject(subjectDid)
+            : [];
+        const dispatchCtx = {
+            ethos: ethosClient,
+            delegateScopes,
+            ...(args.dataProvider ? { dataProvider: args.dataProvider } : {}),
+        };
+        const tools = selectAgentTools({
+            ...(args.tools ? { tools: args.tools } : {}),
+            ...(args.readOnly ? { readOnly: true } : {}),
+        });
+        const maxIterations = Math.max(1, Math.min(HARD_LOCAL_MAX_ITERATIONS, args.maxIterations ?? DEFAULT_LOCAL_MAX_ITERATIONS));
+        // Carry the last turn's billing metadata out of the loop.
+        let lastAuditId = "";
+        let lastFundedBy;
+        let lastReceiptId;
+        const initialMessages = args.messages.map((m) => ({
+            role: m.role,
+            content: m.content,
+        }));
+        const loop = await runAgenticLoopLocal({
+            messages: initialMessages,
+            maxIterations,
+            invokeTurn: async (messages) => {
+                const r = await this.invokeTurn({
+                    ...(args.mandateId !== undefined ? { mandateId: args.mandateId } : {}),
+                    model: args.model,
+                    messages,
+                    tools,
+                    ...(args.system !== undefined ? { system: args.system } : {}),
+                    ...(args.maxTokens !== undefined ? { maxTokens: args.maxTokens } : {}),
+                    ...(args.temperature !== undefined ? { temperature: args.temperature } : {}),
+                    ...(args.signal ? { signal: args.signal } : {}),
+                });
+                lastAuditId = r.auditId;
+                lastFundedBy = r.fundedBy;
+                lastReceiptId = r.receiptId;
+                return {
+                    content: r.content,
+                    stopReason: r.stopReason,
+                    usage: r.usage,
+                    creditsCharged: r.creditsCharged,
+                    walletBalance: r.walletBalance,
+                };
+            },
+            dispatch: (name, input) => dispatchAgentToolLocal(dispatchCtx, name, input),
+        });
+        return {
+            content: loop.finalContent,
+            stopReason: loop.stopReason,
+            iterations: loop.iterations,
+            usage: loop.usage,
+            toolCalls: loop.toolCalls,
+            creditsCharged: loop.creditsCharged,
+            walletBalance: loop.walletBalance,
+            auditId: lastAuditId,
+            ...(lastFundedBy ? { fundedBy: lastFundedBy } : {}),
+            ...(lastReceiptId ? { receiptId: lastReceiptId } : {}),
+        };
+    }
     /**
      * Multimodal Bedrock invoke — image + text → text response.
      * Default model: `claude-sonnet-4-6` (vision-capable, reliable JSON).
@@ -597,6 +732,46 @@ export class ComputeNamespace {
             },
         };
     }
+    /**
+     * Lazily-built EthosNamespace for the local agent dispatch — reuses the
+     * compute deps (auth / endpoints / fetch), so no extra wiring in sdk.ts.
+     */
+    #ethosNs = null;
+    #ethosNamespace() {
+        if (!this.#ethosNs) {
+            this.#ethosNs = new EthosNamespace({
+                auth: this.#deps.auth,
+                endpoints: this.#deps.endpoints,
+                fetch: this.#deps.fetch,
+            });
+        }
+        return this.#ethosNs;
+    }
+    /**
+     * Resolve the subject DID the local agent operates on:
+     *   1. explicit `subjectDid` always wins;
+     *   2. else the signed-in owner;
+     *   3. else (delegate session) the subject of the imported mandate.
+     */
+    #resolveSubjectDid(explicit, mandateId) {
+        if (explicit && explicit.length > 0)
+            return explicit;
+        const owner = this.#deps.auth._getOwnerSigners();
+        if (owner && !owner.destroyed)
+            return owner.did;
+        if (mandateId) {
+            const actor = this.#deps.auth._getDelegateActor(mandateId);
+            if (actor && !actor.destroyed)
+                return actor.subjectDid;
+        }
+        throw new AithosSDKError("sdk_no_signer", "cannot determine the subject DID: sign in as an owner, pass a mandateId for a delegate session, or pass subjectDid explicitly.");
+    }
+    /** Scopes carried by the delegate mandate for `did` (empty if none). */
+    #delegateScopesForSubject(did) {
+        const actor = this.#deps.auth._findDelegateForSubject(did);
+        const raw = actor?.mandate?.scopes;
+        return Array.isArray(raw) ? raw.filter((s) => typeof s === "string") : [];
+    }
     /**
      * Resolve the active signer (owner takes precedence over delegate).
      *

package/dist/src/data.d.ts

@@ -278,17 +278,22 @@ export interface CreateDelegateDataClientArgs {
     readonly fetch?: typeof fetch;
 }
 /**
- * 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 declare function createDelegateDataClient(args: CreateDelegateDataClientArgs): ReadonlyDataClient;
+export declare function createDelegateDataClient(args: CreateDelegateDataClientArgs): DataClient;
 /** An append-only handle on one collection: `insert` and nothing else. */
 export interface AppendOnlyDataCollection {
     readonly name: string;