@gemmein/sdk 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -9,7 +9,7 @@ exports.gemmeinServer = gemmeinServer;
  *  second module). `scripts/sync-version.mjs` rewrites the literal from
  *  package.json before every build (`prebuild`), and a test pins the two
  *  equal, so a bump can never ship with a stale header. */
-exports.SDK_VERSION = "0.7.0"; // synced from package.json — do not edit by hand
+exports.SDK_VERSION = "0.9.0"; // synced from package.json — do not edit by hand
 /** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
  *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
  *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
@@ -391,14 +391,24 @@ class CreditsClient {
 }
 exports.CreditsClient = CreditsClient;
 /**
- * The AI route. `chat` takes the provider's own request body — exactly what
- * you would POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages
- * or Google's generateContent — and answers with the fetch `Response`
- * untouched, streaming intact (SSE stays SSE). Gemmein spends one credit,
- * adds the owner's key, forwards, and passes status and bytes back.
- * Response headers: `x-gemmein-credits-remaining` on every answer that
- * passed the spend; `x-gemmein-credit: refunded` when the provider failed
- * before its first byte.
+ * The AI route. The primary path is a NAMED TOOL defined on the server:
+ * `run(name, inputs)` sends a name and inputs, the server composes the
+ * provider request from the tool's own instructions and template (never
+ * the browser), gates it, spends the tool's credits and streams the
+ * answer back; `runText` is the same call collected to one string;
+ * `calls()` is the signed-in person's own history. `chat` is the RAW
+ * call: it takes the provider's own request body — exactly what you would
+ * POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages or
+ * Google's generateContent — and answers with the fetch `Response`
+ * untouched, streaming intact (SSE stays SSE). Raw calls are off by
+ * default for every provider key (`raw_calls_off`, 403) until the founder
+ * switches them on for that key on the AI tools page. Gemmein spends a
+ * credit, adds the owner's key, forwards, and passes status and bytes
+ * back. Pass `tool` (W9.3b) to a raw call to price and gate it as a named
+ * tool instead of the implicit default (one credit, any allowed model, no
+ * gate). Response headers: `x-gemmein-credits-remaining` on every answer
+ * that passed the spend; `x-gemmein-credit: refunded` when the provider
+ * failed before its first byte.
  */
 class AiClient {
     constructor(config) {
@@ -409,23 +419,34 @@ class AiClient {
      *   for await (const chunk of res.body) { … }
      *
      * Browser sessions only — a server key is refused (`scope_denied`, 403).
-     * Refusals, all `GemmeinError`: `session_required` (401) ·
+     * Refusals, all `GemmeinError`: `raw_calls_off` (403 — raw calls are off
+     * for this provider until the founder switches them on for its key on
+     * the AI tools page; call a named tool with `run` instead) ·
+     * `session_required` (401) ·
      * `credits_exhausted` (402 — the message carries the balance; show your
      * own "buy more" door, which is a product checkout) · `ai_not_configured`
      * (409 — the owner has set no key) · `provider_required` (400) ·
      * `model_not_allowed` (403 — the owner's models list) · `ai_capped`
      * (429 — 20 calls a minute per person; `err.resetAt`) ·
      * `payload_too_large` (413 — 256 KB) · `provider_unreachable` (502,
-     * before the first byte, refunded). Those are GEMMEIN's refusals. The
-     * PROVIDER's own answer — 2xx or not — is returned as it came: an answer
-     * that carries `x-gemmein-credits-remaining` (or `x-gemmein-credit`)
-     * passed the spend, so its status and body are the provider's; read
-     * `res.ok` / `res.status` yourself (a provider 4xx before the first byte
-     * is refunded, header `x-gemmein-credit: refunded`).
+     * before the first byte, refunded). W9.3b, `tool` only: `unknown_tool`
+     * (404 — no tool by that name in this environment) · `tool_disabled`
+     * (403) · `entitlement_required` (403 — the message names the plan or
+     * product that unlocks it) · `model_pinned` (403 — the tool's model is
+     * fixed; leave `model` out of the body). Those are GEMMEIN's refusals.
+     * The PROVIDER's own answer — 2xx or not — is returned as it came: an
+     * answer that carries `x-gemmein-credits-remaining` passed the spend, so
+     * its status and body are the provider's; read `res.ok` / `res.status`
+     * yourself (a provider 4xx before the first byte is refunded, header
+     * `x-gemmein-credit: refunded`). `x-gemmein-tool` names the tool; absent
+     * on the implicit default.
      */
     async chat(body, options = {}) {
         const payload = options.provider ? { provider: options.provider, ...body } : body;
-        const response = await fetch(new URL("/ai/chat", this.config.apiUrl), {
+        const url = new URL("/ai/chat", this.config.apiUrl);
+        if (options.tool)
+            url.searchParams.set("tool", options.tool);
+        const response = await fetch(url, {
             method: "POST",
             body: JSON.stringify(payload),
             headers: await runtimeHeaders(this.config, { "content-type": "application/json" }),
@@ -447,6 +468,91 @@ class AiClient {
         }
         return response;
     }
+    /**
+     * W9.6: run a named tool with INPUTS — the server composes the provider
+     * request from the tool's own instructions and template (never the
+     * browser), gates it, spends its credits and streams the answer back.
+     * The answer is the provider's own shape for the tool's provider (SSE
+     * when `stream`), so read it as you would `chat()`'s.
+     *
+     *   const res = await g.ai.run("summarise", { text }, { stream: true });
+     *
+     * Browser sessions only — a server key is refused (`scope_denied`, 403).
+     * Refusals, all `GemmeinError`: `session_required` (401 — sign in
+     * first) · `ai_capped` (429 — 20 calls a minute per person;
+     * `err.resetAt`) · `unknown_tool` (404 — no tool by that name in this
+     * environment) · `tool_disabled` (403 — the owner switched it off) ·
+     * `entitlement_required` (403 — the message names the plan or product
+     * it needs) · `payload_too_large` (413 — inputs over 64 KB) ·
+     * `invalid_body` (400 — the body must be a JSON object
+     * `{ inputs, stream? }`) · `invalid_inputs` (400 — the message names the
+     * input and the rule) · `tool_incomplete` (409 — the tool composes
+     * nothing; a founder's fix) · `ai_not_configured` (409 — the tool's
+     * provider has no key set; the owner pastes one) · `credits_exhausted`
+     * (402 — the message names the tool, its price and the balance) ·
+     * `provider_unreachable` (502 — no answer before the first byte; the
+     * tool's credits are refunded, header `x-gemmein-credit: refunded`).
+     * The provider's own answer — 2xx or not — is returned as it came; read
+     * `res.ok` yourself. `x-gemmein-tool` names the tool.
+     */
+    async run(tool, inputs = {}, options = {}) {
+        const url = new URL(`/ai/run/${encodeURIComponent(tool)}`, this.config.apiUrl);
+        const response = await fetch(url, {
+            method: "POST",
+            body: JSON.stringify({ inputs, ...(options.stream ? { stream: true } : {}) }),
+            headers: await runtimeHeaders(this.config, { "content-type": "application/json" }),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (!response.ok) {
+            if (isForwardedAnswer(response)) {
+                const peek = (await response.clone().json().catch(() => null));
+                if (peek?.code !== "provider_unreachable")
+                    return response;
+            }
+            const errorBody = await readErrorBody(response);
+            if (errorBody.code === "auth_expired")
+                await this.config.tokenStore.clear();
+            throw new GemmeinError({ status: response.status, ...errorBody });
+        }
+        return response;
+    }
+    /**
+     * W9.6: `run()` without a stream, as one string — the text lifted out
+     * of the tool's provider's answer (the same readers `text()` uses).
+     * `run()`'s refusals, plus: a provider's own non-2xx throws
+     * `provider_error` with the provider's status and message; an answer
+     * with no text to lift out throws `invalid_response` (status 0).
+     *
+     *   const summary = await g.ai.runText("summarise", { text });
+     */
+    async runText(tool, inputs = {}, options = {}) {
+        const response = await this.run(tool, inputs, options);
+        if (!response.ok) {
+            throw new GemmeinError({ status: response.status, code: "provider_error", message: await providerErrorMessage(response) });
+        }
+        const data = (await response.json());
+        const text = extractAiText(data);
+        if (text === null) {
+            throw new GemmeinError({ status: 0, code: "invalid_response", message: "the provider answered without any text — use g.ai.run() with { stream: true } and read the stream" });
+        }
+        return text;
+    }
+    /**
+     * W9.6 §16: the signed-in person's OWN AI calls, newest first — what they
+     * ran, when, what it cost, how it ended; the prompt and answer only where
+     * the tool keeps them. Session required.
+     *
+     *   const { calls, nextCursor } = await g.ai.calls();
+     */
+    async calls(options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit)
+            params.set("limit", String(options.limit));
+        if (options.before)
+            params.set("before", options.before);
+        const query = params.toString();
+        return runtimeRequest(this.config, `/auth/ai-calls${query ? `?${query}` : ""}`);
+    }
     /**
      * The non-streaming convenience: one call, one string. Pass a body that
      * does NOT stream (`stream` unset or false); the provider's JSON answer is

package/dist/index.d.cts

@@ -120,13 +120,13 @@ export type AuthSession = {
  *  second module). `scripts/sync-version.mjs` rewrites the literal from
  *  package.json before every build (`prebuild`), and a test pins the two
  *  equal, so a bump can never ship with a stale header. */
-export declare const SDK_VERSION = "0.7.0";
+export declare const SDK_VERSION = "0.9.0";
 /** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
  *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
  *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
  *  misbehaving integration can be attributed to an SDK version from day
  *  one. It is a report, not a proof — any caller can set it. */
-export declare const CLIENT_INFO = "gemmein-sdk/0.7.0";
+export declare const CLIENT_INFO = "gemmein-sdk/0.9.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -387,10 +387,37 @@ export declare class AccountClient {
     delete(): Promise<unknown>;
 }
 export type AiProvider = "openai" | "anthropic" | "google";
+/** W9.6 §16: one of the person's own AI calls, as `g.ai.calls()` lists them. */
+export type AiCallRecord = {
+    id: string;
+    tool: string;
+    kind: string;
+    provider: string;
+    model: string | null;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    credits: number;
+    outcome: "ok" | "refused" | "provider_error" | "unreachable" | "client_closed" | "stream_ended";
+    refusalCode: string | null;
+    latencyMs: number | null;
+    prompt: string | null;
+    answer: string | null;
+    createdAt: string;
+};
 export type AiChatOptions = {
     /** Which configured provider answers. Optional when exactly one key is
-     *  set; refused `provider_required` (400) when it is ambiguous. */
+     *  set; refused `provider_required` (400) when it is ambiguous. Refused
+     *  `invalid_body` when `tool` is also set and disagrees with the named
+     *  tool's own provider — leave `provider` out when you pass `tool`. */
     provider?: AiProvider;
+    /** W9.3b: a named AI tool (owner-configured in the console — credits,
+     *  gate and provider/model are the tool's, not this call's). Sent as
+     *  `?tool=`, never in the body. Omitted → the implicit default tool: one
+     *  credit, any allowed model, no gate. With or without `tool`, `chat` is
+     *  a RAW call — off by default (`raw_calls_off`, 403) until the founder
+     *  switches raw calls on for that provider's key on the AI tools page;
+     *  the normal path to a named tool is `run(name, inputs)`. */
+    tool?: string;
     /** Abort the call — the stream closes; a call that dies mid-stream is
      *  not refunded. */
     signal?: AbortSignal;
@@ -426,14 +453,24 @@ export declare class CreditsClient {
     }>;
 }
 /**
- * The AI route. `chat` takes the provider's own request body — exactly what
- * you would POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages
- * or Google's generateContent — and answers with the fetch `Response`
- * untouched, streaming intact (SSE stays SSE). Gemmein spends one credit,
- * adds the owner's key, forwards, and passes status and bytes back.
- * Response headers: `x-gemmein-credits-remaining` on every answer that
- * passed the spend; `x-gemmein-credit: refunded` when the provider failed
- * before its first byte.
+ * The AI route. The primary path is a NAMED TOOL defined on the server:
+ * `run(name, inputs)` sends a name and inputs, the server composes the
+ * provider request from the tool's own instructions and template (never
+ * the browser), gates it, spends the tool's credits and streams the
+ * answer back; `runText` is the same call collected to one string;
+ * `calls()` is the signed-in person's own history. `chat` is the RAW
+ * call: it takes the provider's own request body — exactly what you would
+ * POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages or
+ * Google's generateContent — and answers with the fetch `Response`
+ * untouched, streaming intact (SSE stays SSE). Raw calls are off by
+ * default for every provider key (`raw_calls_off`, 403) until the founder
+ * switches them on for that key on the AI tools page. Gemmein spends a
+ * credit, adds the owner's key, forwards, and passes status and bytes
+ * back. Pass `tool` (W9.3b) to a raw call to price and gate it as a named
+ * tool instead of the implicit default (one credit, any allowed model, no
+ * gate). Response headers: `x-gemmein-credits-remaining` on every answer
+ * that passed the spend; `x-gemmein-credit: refunded` when the provider
+ * failed before its first byte.
  */
 export declare class AiClient {
     private readonly config;
@@ -443,21 +480,86 @@ export declare class AiClient {
      *   for await (const chunk of res.body) { … }
      *
      * Browser sessions only — a server key is refused (`scope_denied`, 403).
-     * Refusals, all `GemmeinError`: `session_required` (401) ·
+     * Refusals, all `GemmeinError`: `raw_calls_off` (403 — raw calls are off
+     * for this provider until the founder switches them on for its key on
+     * the AI tools page; call a named tool with `run` instead) ·
+     * `session_required` (401) ·
      * `credits_exhausted` (402 — the message carries the balance; show your
      * own "buy more" door, which is a product checkout) · `ai_not_configured`
      * (409 — the owner has set no key) · `provider_required` (400) ·
      * `model_not_allowed` (403 — the owner's models list) · `ai_capped`
      * (429 — 20 calls a minute per person; `err.resetAt`) ·
      * `payload_too_large` (413 — 256 KB) · `provider_unreachable` (502,
-     * before the first byte, refunded). Those are GEMMEIN's refusals. The
-     * PROVIDER's own answer — 2xx or not — is returned as it came: an answer
-     * that carries `x-gemmein-credits-remaining` (or `x-gemmein-credit`)
-     * passed the spend, so its status and body are the provider's; read
-     * `res.ok` / `res.status` yourself (a provider 4xx before the first byte
-     * is refunded, header `x-gemmein-credit: refunded`).
+     * before the first byte, refunded). W9.3b, `tool` only: `unknown_tool`
+     * (404 — no tool by that name in this environment) · `tool_disabled`
+     * (403) · `entitlement_required` (403 — the message names the plan or
+     * product that unlocks it) · `model_pinned` (403 — the tool's model is
+     * fixed; leave `model` out of the body). Those are GEMMEIN's refusals.
+     * The PROVIDER's own answer — 2xx or not — is returned as it came: an
+     * answer that carries `x-gemmein-credits-remaining` passed the spend, so
+     * its status and body are the provider's; read `res.ok` / `res.status`
+     * yourself (a provider 4xx before the first byte is refunded, header
+     * `x-gemmein-credit: refunded`). `x-gemmein-tool` names the tool; absent
+     * on the implicit default.
      */
     chat(body: Record<string, unknown>, options?: AiChatOptions): Promise<Response>;
+    /**
+     * W9.6: run a named tool with INPUTS — the server composes the provider
+     * request from the tool's own instructions and template (never the
+     * browser), gates it, spends its credits and streams the answer back.
+     * The answer is the provider's own shape for the tool's provider (SSE
+     * when `stream`), so read it as you would `chat()`'s.
+     *
+     *   const res = await g.ai.run("summarise", { text }, { stream: true });
+     *
+     * Browser sessions only — a server key is refused (`scope_denied`, 403).
+     * Refusals, all `GemmeinError`: `session_required` (401 — sign in
+     * first) · `ai_capped` (429 — 20 calls a minute per person;
+     * `err.resetAt`) · `unknown_tool` (404 — no tool by that name in this
+     * environment) · `tool_disabled` (403 — the owner switched it off) ·
+     * `entitlement_required` (403 — the message names the plan or product
+     * it needs) · `payload_too_large` (413 — inputs over 64 KB) ·
+     * `invalid_body` (400 — the body must be a JSON object
+     * `{ inputs, stream? }`) · `invalid_inputs` (400 — the message names the
+     * input and the rule) · `tool_incomplete` (409 — the tool composes
+     * nothing; a founder's fix) · `ai_not_configured` (409 — the tool's
+     * provider has no key set; the owner pastes one) · `credits_exhausted`
+     * (402 — the message names the tool, its price and the balance) ·
+     * `provider_unreachable` (502 — no answer before the first byte; the
+     * tool's credits are refunded, header `x-gemmein-credit: refunded`).
+     * The provider's own answer — 2xx or not — is returned as it came; read
+     * `res.ok` yourself. `x-gemmein-tool` names the tool.
+     */
+    run(tool: string, inputs?: Record<string, string | number | boolean>, options?: {
+        stream?: boolean;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /**
+     * W9.6: `run()` without a stream, as one string — the text lifted out
+     * of the tool's provider's answer (the same readers `text()` uses).
+     * `run()`'s refusals, plus: a provider's own non-2xx throws
+     * `provider_error` with the provider's status and message; an answer
+     * with no text to lift out throws `invalid_response` (status 0).
+     *
+     *   const summary = await g.ai.runText("summarise", { text });
+     */
+    runText(tool: string, inputs?: Record<string, string | number | boolean>, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /**
+     * W9.6 §16: the signed-in person's OWN AI calls, newest first — what they
+     * ran, when, what it cost, how it ended; the prompt and answer only where
+     * the tool keeps them. Session required.
+     *
+     *   const { calls, nextCursor } = await g.ai.calls();
+     */
+    calls(options?: {
+        limit?: number;
+        before?: string | null;
+    }): Promise<{
+        calls: AiCallRecord[];
+        nextCursor: string | null;
+    }>;
     /**
      * The non-streaming convenience: one call, one string. Pass a body that
      * does NOT stream (`stream` unset or false); the provider's JSON answer is

package/dist/index.d.ts

@@ -120,13 +120,13 @@ export type AuthSession = {
  *  second module). `scripts/sync-version.mjs` rewrites the literal from
  *  package.json before every build (`prebuild`), and a test pins the two
  *  equal, so a bump can never ship with a stale header. */
-export declare const SDK_VERSION = "0.7.0";
+export declare const SDK_VERSION = "0.9.0";
 /** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
  *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
  *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
  *  misbehaving integration can be attributed to an SDK version from day
  *  one. It is a report, not a proof — any caller can set it. */
-export declare const CLIENT_INFO = "gemmein-sdk/0.7.0";
+export declare const CLIENT_INFO = "gemmein-sdk/0.9.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -387,10 +387,37 @@ export declare class AccountClient {
     delete(): Promise<unknown>;
 }
 export type AiProvider = "openai" | "anthropic" | "google";
+/** W9.6 §16: one of the person's own AI calls, as `g.ai.calls()` lists them. */
+export type AiCallRecord = {
+    id: string;
+    tool: string;
+    kind: string;
+    provider: string;
+    model: string | null;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    credits: number;
+    outcome: "ok" | "refused" | "provider_error" | "unreachable" | "client_closed" | "stream_ended";
+    refusalCode: string | null;
+    latencyMs: number | null;
+    prompt: string | null;
+    answer: string | null;
+    createdAt: string;
+};
 export type AiChatOptions = {
     /** Which configured provider answers. Optional when exactly one key is
-     *  set; refused `provider_required` (400) when it is ambiguous. */
+     *  set; refused `provider_required` (400) when it is ambiguous. Refused
+     *  `invalid_body` when `tool` is also set and disagrees with the named
+     *  tool's own provider — leave `provider` out when you pass `tool`. */
     provider?: AiProvider;
+    /** W9.3b: a named AI tool (owner-configured in the console — credits,
+     *  gate and provider/model are the tool's, not this call's). Sent as
+     *  `?tool=`, never in the body. Omitted → the implicit default tool: one
+     *  credit, any allowed model, no gate. With or without `tool`, `chat` is
+     *  a RAW call — off by default (`raw_calls_off`, 403) until the founder
+     *  switches raw calls on for that provider's key on the AI tools page;
+     *  the normal path to a named tool is `run(name, inputs)`. */
+    tool?: string;
     /** Abort the call — the stream closes; a call that dies mid-stream is
      *  not refunded. */
     signal?: AbortSignal;
@@ -426,14 +453,24 @@ export declare class CreditsClient {
     }>;
 }
 /**
- * The AI route. `chat` takes the provider's own request body — exactly what
- * you would POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages
- * or Google's generateContent — and answers with the fetch `Response`
- * untouched, streaming intact (SSE stays SSE). Gemmein spends one credit,
- * adds the owner's key, forwards, and passes status and bytes back.
- * Response headers: `x-gemmein-credits-remaining` on every answer that
- * passed the spend; `x-gemmein-credit: refunded` when the provider failed
- * before its first byte.
+ * The AI route. The primary path is a NAMED TOOL defined on the server:
+ * `run(name, inputs)` sends a name and inputs, the server composes the
+ * provider request from the tool's own instructions and template (never
+ * the browser), gates it, spends the tool's credits and streams the
+ * answer back; `runText` is the same call collected to one string;
+ * `calls()` is the signed-in person's own history. `chat` is the RAW
+ * call: it takes the provider's own request body — exactly what you would
+ * POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages or
+ * Google's generateContent — and answers with the fetch `Response`
+ * untouched, streaming intact (SSE stays SSE). Raw calls are off by
+ * default for every provider key (`raw_calls_off`, 403) until the founder
+ * switches them on for that key on the AI tools page. Gemmein spends a
+ * credit, adds the owner's key, forwards, and passes status and bytes
+ * back. Pass `tool` (W9.3b) to a raw call to price and gate it as a named
+ * tool instead of the implicit default (one credit, any allowed model, no
+ * gate). Response headers: `x-gemmein-credits-remaining` on every answer
+ * that passed the spend; `x-gemmein-credit: refunded` when the provider
+ * failed before its first byte.
  */
 export declare class AiClient {
     private readonly config;
@@ -443,21 +480,86 @@ export declare class AiClient {
      *   for await (const chunk of res.body) { … }
      *
      * Browser sessions only — a server key is refused (`scope_denied`, 403).
-     * Refusals, all `GemmeinError`: `session_required` (401) ·
+     * Refusals, all `GemmeinError`: `raw_calls_off` (403 — raw calls are off
+     * for this provider until the founder switches them on for its key on
+     * the AI tools page; call a named tool with `run` instead) ·
+     * `session_required` (401) ·
      * `credits_exhausted` (402 — the message carries the balance; show your
      * own "buy more" door, which is a product checkout) · `ai_not_configured`
      * (409 — the owner has set no key) · `provider_required` (400) ·
      * `model_not_allowed` (403 — the owner's models list) · `ai_capped`
      * (429 — 20 calls a minute per person; `err.resetAt`) ·
      * `payload_too_large` (413 — 256 KB) · `provider_unreachable` (502,
-     * before the first byte, refunded). Those are GEMMEIN's refusals. The
-     * PROVIDER's own answer — 2xx or not — is returned as it came: an answer
-     * that carries `x-gemmein-credits-remaining` (or `x-gemmein-credit`)
-     * passed the spend, so its status and body are the provider's; read
-     * `res.ok` / `res.status` yourself (a provider 4xx before the first byte
-     * is refunded, header `x-gemmein-credit: refunded`).
+     * before the first byte, refunded). W9.3b, `tool` only: `unknown_tool`
+     * (404 — no tool by that name in this environment) · `tool_disabled`
+     * (403) · `entitlement_required` (403 — the message names the plan or
+     * product that unlocks it) · `model_pinned` (403 — the tool's model is
+     * fixed; leave `model` out of the body). Those are GEMMEIN's refusals.
+     * The PROVIDER's own answer — 2xx or not — is returned as it came: an
+     * answer that carries `x-gemmein-credits-remaining` passed the spend, so
+     * its status and body are the provider's; read `res.ok` / `res.status`
+     * yourself (a provider 4xx before the first byte is refunded, header
+     * `x-gemmein-credit: refunded`). `x-gemmein-tool` names the tool; absent
+     * on the implicit default.
      */
     chat(body: Record<string, unknown>, options?: AiChatOptions): Promise<Response>;
+    /**
+     * W9.6: run a named tool with INPUTS — the server composes the provider
+     * request from the tool's own instructions and template (never the
+     * browser), gates it, spends its credits and streams the answer back.
+     * The answer is the provider's own shape for the tool's provider (SSE
+     * when `stream`), so read it as you would `chat()`'s.
+     *
+     *   const res = await g.ai.run("summarise", { text }, { stream: true });
+     *
+     * Browser sessions only — a server key is refused (`scope_denied`, 403).
+     * Refusals, all `GemmeinError`: `session_required` (401 — sign in
+     * first) · `ai_capped` (429 — 20 calls a minute per person;
+     * `err.resetAt`) · `unknown_tool` (404 — no tool by that name in this
+     * environment) · `tool_disabled` (403 — the owner switched it off) ·
+     * `entitlement_required` (403 — the message names the plan or product
+     * it needs) · `payload_too_large` (413 — inputs over 64 KB) ·
+     * `invalid_body` (400 — the body must be a JSON object
+     * `{ inputs, stream? }`) · `invalid_inputs` (400 — the message names the
+     * input and the rule) · `tool_incomplete` (409 — the tool composes
+     * nothing; a founder's fix) · `ai_not_configured` (409 — the tool's
+     * provider has no key set; the owner pastes one) · `credits_exhausted`
+     * (402 — the message names the tool, its price and the balance) ·
+     * `provider_unreachable` (502 — no answer before the first byte; the
+     * tool's credits are refunded, header `x-gemmein-credit: refunded`).
+     * The provider's own answer — 2xx or not — is returned as it came; read
+     * `res.ok` yourself. `x-gemmein-tool` names the tool.
+     */
+    run(tool: string, inputs?: Record<string, string | number | boolean>, options?: {
+        stream?: boolean;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /**
+     * W9.6: `run()` without a stream, as one string — the text lifted out
+     * of the tool's provider's answer (the same readers `text()` uses).
+     * `run()`'s refusals, plus: a provider's own non-2xx throws
+     * `provider_error` with the provider's status and message; an answer
+     * with no text to lift out throws `invalid_response` (status 0).
+     *
+     *   const summary = await g.ai.runText("summarise", { text });
+     */
+    runText(tool: string, inputs?: Record<string, string | number | boolean>, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /**
+     * W9.6 §16: the signed-in person's OWN AI calls, newest first — what they
+     * ran, when, what it cost, how it ended; the prompt and answer only where
+     * the tool keeps them. Session required.
+     *
+     *   const { calls, nextCursor } = await g.ai.calls();
+     */
+    calls(options?: {
+        limit?: number;
+        before?: string | null;
+    }): Promise<{
+        calls: AiCallRecord[];
+        nextCursor: string | null;
+    }>;
     /**
      * The non-streaming convenience: one call, one string. Pass a body that
      * does NOT stream (`stream` unset or false); the provider's JSON answer is