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

package/README.md

@@ -55,6 +55,40 @@ const reply = await sdk.compute.invokeBedrock({
 console.log(reply.content);
 ```
 
+## Transcribing audio → text
+
+`sdk.compute.invokeTranscribe` turns an audio `Blob` into text through AWS
+Transcribe. It does one thing — audio → text — and **stores nothing**: it
+returns the transcript and you decide what to do with it (write it to an
+ethos, a PDS, your own database, email it, or throw it away).
+
+```ts
+// Browser: a Blob from MediaRecorder; backend: a Blob from a Buffer.
+const result = await sdk.compute.invokeTranscribe({
+  audio: blob,                          // Blob/File (Node 18+ has global Blob)
+  model: "transcribe:aws-fr-standard",  // default; also aws-en-standard
+  languageCode: "fr-FR",                // optional
+  // durationSecOverride: 127,          // REQUIRED on backends (no DOM probe)
+  onProgress: (s) => console.log(s.phase), // uploading → starting → processing → completed
+});
+
+console.log(result.text);          // "Bonjour, je voulais te dire que…"
+console.log(result.segments);      // [{ start_sec, end_sec, text }]
+console.log(result.creditsCharged);
+
+// Then YOU choose where it goes — the compute has no opinion:
+await myEthos.addRevision(result.text);   // or PDS, DB, email, nothing…
+```
+
+The core is isomorphic (Node + browser) and depends only on `Blob`, `fetch`
+and timers. Browser-only resilience is opt-in and framework-agnostic:
+`sdk.compute.transcribeDraft` (IndexedDB queue of recordings) and
+`sdk.compute.listLocalPendingTranscribes()` /
+`subscribeLocalPendingTranscribes()` / `resumeTranscribe(jobId)` recover jobs
+across reloads. React users get `useAithosTranscribePendingJobs(sdk.compute)`
+from `@aithos/sdk/react`. Advanced callers can drive the flow manually with
+`prepareTranscribe` / `startTranscribe` / `getTranscribeStatus`.
+
 ## Delegating compute to an agent — opt-in token spending
 
 To let an agent (or another user, or a third-party app) invoke Bedrock
@@ -100,15 +134,176 @@ network — they fail fast with a precise `AithosSDKError`:
   set — useful for agents that only consume tokens (e.g. creative
   assistants) without seeing any of your data.
 
+## Custodial auth — onboarding users without a recovery file
+
+Three new methods on `AithosAuth` let an app create and authenticate
+its end-users via a server-managed custody flow — the user only needs
+an email address and a password sent by mail. No recovery file, no
+Google account, no client-side cryptography to handle.
+
+The model is honest custody: Aithos KMS-wraps the user's Ed25519
+identity seeds, and unwraps them on every sign-in after password
+verification. Equivalent to how Coinbase or any hosted SaaS keeps your
+private key. Annunciated to the user in the welcome email.
+
+```ts
+import { AithosSDK } from "@aithos/sdk";
+
+// ─── Server-side: sign-up ───────────────────────────────────────────
+// MUST run on your backend. The API key is a server secret —
+// provisioned by Aithos via the operator runbook.
+const sdk = new AithosSDK({ identity });
+const result = await sdk.auth.signUpCustodial({
+  apiKey: process.env.AITHOS_API_KEY!,
+  email: "alice@example.com",
+  displayName: "Alice",
+});
+// → { userId, did, handle, email, mailSent }
+// The user receives an email with their password and a sign-in link.
+
+// ─── Browser-side: sign-in ──────────────────────────────────────────
+// User pastes the password from their mail into your sign-in form,
+// then your frontend calls this. No API key needed — the password
+// is the credential.
+const { session, passwordMustChange } = await sdk.auth.signInCustodial({
+  email: "alice@example.com",
+  password: "MyTempPass32chars",
+});
+// Local KeyStore is now hydrated with the 5 Ed25519 sphere seeds
+// (root, public, circle, self, #data) — the user can publish ethos
+// editions, mint mandates, invoke compute, and own PDS data/asset
+// collections (signed under the dedicated #data sphere), exactly as if
+// they had signed in via a recovery file or Google SSO.
+if (passwordMustChange) {
+  // Optional: nudge the user to set their own password via the
+  // standard reset flow.
+}
+
+// ─── Browser-side: request password reset ───────────────────────────
+// The backend always returns silently (anti-enumeration). If the email
+// is registered AND in custodial mode AND not in cooldown AND under the
+// daily cap, a magic-link email is sent to the address.
+await sdk.auth.requestPasswordReset({ email: "alice@example.com" });
+```
+
+The reset finalization (collecting the new password from the user) is
+done on a small web page hosted by Aithos at `https://app.aithos.be/reset`
+(or your app's own `reset_base_url` if you've registered one — see the
+operator runbook). The page POSTs to `/auth/custodial/reset/finalize`
+and returns the user to your sign-in page on success.
+
+### Getting an API key
+
+API keys are provisioned out-of-band by Aithos. Contact the maintainer
+(or use the self-service console at `aithos.be/console` when it ships
+in V2). The pattern is `aithos_<env>_<32 chars b58>`. Keep it in your
+backend's secrets manager — never in browser code.
+
+### Trade-offs vs. the zk and Google SSO flows
+
+|                | zk (recovery file)         | Google SSO (KMS)     | **Custodial** |
+|----------------|----------------------------|----------------------|---------------|
+| User burden    | downloads `recovery.json`  | Google consent       | email only    |
+| Password reset | requires recovery file     | re-auth via Google   | magic-link mail |
+| Trust model    | zero-knowledge (you only)  | Aithos + Google      | Aithos only   |
+| Multi-device   | re-import recovery         | re-Google            | email + password |
+| SDK signing capability | full                | full                 | full          |
+
+Custodial is the right default for SDK-integrated apps that want
+SaaS-grade UX. zk is the right default for power users who want
+sovereign custody. SSO is the right default for users already invested
+in the Google ecosystem.
+
+## Extracting webpages without an LLM
+
+`sdk.web` is a token-priced primitive that lets your agent read a
+public webpage and get back cleaned HTML, purged CSS and a
+deterministic visual signature — all computed server-side without an
+LLM in the loop. Pricing is a flat **1 microcredit** per successful
+extraction (refunded on failure), versus ~30 mc for a comparable
+LLM-based extraction.
+
+```ts
+import { AithosSDK } from "@aithos/sdk";
+
+const sdk = new AithosSDK({ auth, appDid });
+
+const { data, creditsCharged } = await sdk.web.extract({
+  url: "https://example.com",
+});
+
+console.log(data.meta.title);             // "Example Domain"
+console.log(data.visual_signature.colors.primary); // "#0078d4"
+console.log(data.styles.css.length);      // purged + minified CSS
+```
+
+Owners can mint a mandate for delegate-only extraction:
+
+```ts
+import { WEB_EXTRACT_SCOPE } from "@aithos/sdk";
+
+await sdk.mandates.create({
+  appDid: "did:aithos:app:my-agent",
+  scopes: [WEB_EXTRACT_SCOPE],
+  // ...
+});
+```
+
+## Calling a third-party Aithos-aware backend
+
+If your app talks to its own backend (a service you built that verifies
+Aithos envelopes per spec §11.2 using
+`@aithos/protocol-core/envelope`), use `sdk.auth.signEnvelope` to sign
+the request with the same primitive that SDK namespaces use internally
+for `api.aithos.be`. No JWT, no shadow session — the user's DID in the
+envelope's `iss` field is the identity.
+
+```ts
+import { AithosSDK, type SignedEnvelope } from "@aithos/sdk";
+
+// Sign a request to your own backend with the active owner's
+// public-sphere key. Default TTL is 60 s.
+const envelope: SignedEnvelope = await sdk.auth.signEnvelope({
+  aud: "https://api.example.com/v1/widgets",
+  method: "myapp.widgets.create",
+  params: { name: "Widget #1" },
+});
+
+await fetch("https://api.example.com/v1/widgets", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    id: crypto.randomUUID(),
+    method: "myapp.widgets.create",
+    params: { name: "Widget #1", _envelope: envelope },
+  }),
+});
+```
+
+The envelope binds the signature to `(iss, aud, method, params_hash,
+nonce, iat, exp)`, so a single envelope cannot be replayed against a
+different endpoint, method, or payload. Throws
+`AithosSDKError("auth_not_signed_in")` if no owner is loaded; throws
+`AithosSDKError("auth_invalid_sphere")` if you pass a sphere outside
+`"root" | "public" | "circle" | "self"` (default is `"public"`).
+
+Server-side, your backend verifies the envelope with
+`@aithos/protocol-core`'s `verifyEnvelope` (the 9-step check from spec
+§11.4) — same algorithm that `api.aithos.be` uses, no re-implementation
+needed.
+
 ## What lives where
 
-| Namespace        | Purpose                                                                                    |
-| ---------------- | ------------------------------------------------------------------------------------------ |
-| `sdk.compute`    | Bedrock invocation through the Aithos compute proxy (signed envelope, wallet enforcement). |
-| `sdk.wallet`     | Stripe Checkout sessions for credit-pack top-ups, balance helpers.                         |
-| `sdk.ethos`      | Ethos-zone composition / parsing — re-exported from `@aithos/protocol-client`.             |
-| `sdk.onboarding` | First-run identity / DID flows — re-exported.                                              |
-| `sdk.mandates`   | Mint / verify mandates — re-exported.                                                      |
+| Namespace                  | Purpose                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `sdk.auth`                 | Sign-in, sign-up, key custody — and `signEnvelope` for calls to your own Aithos-aware backend. |
+| `sdk.compute`              | Bedrock invocation through the Aithos compute proxy (signed envelope, wallet enforcement). |
+| `sdk.web`                  | Webpage extraction without an LLM through the web extractor proxy (1 mc / call).           |
+| `sdk.wallet`               | Stripe Checkout sessions for credit-pack top-ups, balance helpers.                         |
+| `sdk.ethos`                | Ethos-zone composition / parsing — re-exported from `@aithos/protocol-client`.             |
+| `sdk.onboarding`           | First-run identity / DID flows — re-exported.                                              |
+| `sdk.mandates`             | Mint / verify mandates — re-exported.                                                      |
 
 ## License
 

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