@gemmein/sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -12,6 +12,36 @@ the same release.
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-09-07
+
+### Keys that know what they are, production sync, and AI tools defined on the server (engine 0.10.0, sdk 0.9.0, mcp 0.6.0)
+
+- **`g.ai.run(tool, inputs, { stream? })` / `g.ai.runText(tool, inputs)`** — call a
+  named AI tool with inputs only; the server composes the provider request
+  from the tool's own instructions and template, gates it, spends its
+  credits and streams the answer back in the provider's own shape.
+  Refusals: `invalid_inputs` (400), `tool_incomplete` (409), plus the tool
+  codes `g.ai.chat` already answered.
+- **`g.ai.calls()`** — the signed-in person's own AI calls, newest first,
+  keyset-paged (`AiCallRecord`): tool, provider, model, tokens, credits,
+  outcome, latency, and the prompt and answer where the tool keeps them.
+- **Raw calls are off by default.** `g.ai.chat(body)` answers
+  `403 raw_calls_off` unless the owner switches raw calls on for that
+  provider's key on the AI tools page. Migration note: an app built on
+  `g.ai.chat` needs that switch, or a named tool through `g.ai.run`.
+- **Server keys cannot sign in as the account owner or admin.**
+  `gemmeinServer(sk).testSession(email)` refuses those two emails with
+  `scope_denied`; test people sign in as before. Linking and dev sync use
+  the app's CLI key (`sk_cli_…`, Setup page); production sync uses a
+  one-hour Sync key (`sk_sync_…`). `secret_key_expired` (403) names an
+  expired sync key's instant.
+- CLI: `npx gemmein sync` links with ONE paste (the CLI key); `npx gemmein
+  sync --live` carries relays and AI tools into production behind a sync
+  key and the typed word `live`, never deletes, asks before replacing a
+  row edited in the dashboard (`--overwrite`). A relay's name is fixed once
+  created. Tool files gain `kind`, `instructions`, `promptTemplate`,
+  `inputs`, `recordCalls`.
+
 ## [0.8.0] — 2026-09-05
 
 ### Products are provider-neutral (engine 0.9.0, sdk 0.8.0, mcp 0.5.0)

package/README.md

@@ -292,7 +292,9 @@ try {
 |--------|------------|----------------|
 | `pk_test_...` | Development | Frontend code — safe to expose |
 | `pk_live_...` | Production | Frontend code — safe to expose |
-| `sk_dev_...` / `sk_live_...` | Dev / Prod | Server env vars only |
+| `sk_dev_...` / `sk_live_...` | Dev / Prod | Server env vars only — runs your app; never links or syncs |
+| `sk_cli_...` | Development | The CLI key, shown on Setup: what `gemmein sync` and `gemmein go-live` act with. Lives in `gemmein/.data/`, never in git |
+| `sk_sync_...` | Production | A one-hour sync key (Secret keys → production): `gemmein sync --live` carries relays and AI tools into production. Pasted, used, never saved |
 
 Environments are fully isolated: different data, different users, different collections.
 

package/REFERENCE.md

@@ -353,30 +353,79 @@ connected.
 
 ---
 
-## AI — `g.ai.chat` / `g.ai.text`
+## AI — `g.ai.run` / `g.ai.runText` / `g.ai.calls` (and the raw `g.ai.chat` / `g.ai.text`)
 
 Your app talks to **OpenAI, Anthropic or Google** through Gemmein, on the
 **owner's own provider key**, which never reaches the browser, through a
-**named AI tool** — a slug the owner prices in credits, pins a model or
-provider to, and gates behind an entitlement, from the dashboard's Tools
-page or a local `gemmein/ai/tools/<name>.json` file. Removing a tool is a
-step-up action, like removing a key. A call that names no
-`tool` runs as the **default tool**: one credit, the app's configured
-provider, any allowed model — every existing integration that never passed
-`tool` keeps working unchanged. The owner pastes each provider key once in
-the dashboard's Keys room; it is write-only from then on. The route
-forwards the provider's own request body as sent — minus the `provider`
-field, and for Google minus `model` and `stream`, which ride the URL — adds
-the provider's auth headers, `content-type` and `accept`, and passes the
-status and the bytes straight back — a stream stays a stream. It does not
-choose models, cache, summarise, moderate or reshape anything, and it is for
-the browser only: a server key is refused (`403 scope_denied`) — a server
-calls the provider directly.
+**named AI tool whose definition lives on the server** (W9.6): the
+instructions (system prompt), the prompt template, the inputs it accepts,
+the pinned model, the caps — beside the price in credits and the
+entitlement gate. The app sends a **name and inputs**; the server composes
+the provider request in the provider's own grammar, gates it, spends the
+tool's credits, runs it and streams the answer back. The owner prices and
+gates the tool on the dashboard's AI tools page; the implementation is
+written there too, or as a file at `gemmein/ai/tools/<name>.json` that
+`npx gemmein sync` carries (`--live` into production with a sync key). A
+file carries at least `label`, `provider` and `credits` (its name is the
+file name). On every sync the file's implementation (`provider`, `model`,
+`kind`, `instructions`, `promptTemplate`, `inputs`, `bounds`) applies; its
+commerce values (`label`, `credits`, `requires`, `enabled`, `recordCalls`)
+apply once, at creation — after that the dashboard owns them. In
+development, sync also writes a tool that exists only in the cloud back to
+`gemmein/ai/tools/` as a file; in production such a row is left as it is.
+A tool's name is fixed once created. Removing a tool is a step-up action, like
+removing a key.
+
+**Raw calls are off by default.** `g.ai.chat(body)` — the browser sending
+the provider's own request body — answers `403 raw_calls_off` unless the
+owner switches **raw calls** on for that provider's key on the AI tools page. Behind the switch, the raw route is what it always was: the body is
+forwarded as sent (minus `provider`, and for Google minus `model` and
+`stream`, which ride the URL), the provider's own status and bytes pass
+straight back, a stream stays a stream, and a call that names no `tool`
+runs as the **default tool** (one credit, the configured provider, any
+allowed model). `gemmein dev` with no key keeps raw calls open — the fake
+answers and there is no switch locally. Both routes are for the browser
+only: a server key is refused (`403 scope_denied`) — a server calls the
+provider directly.
+
+**Every call lands on `ai_calls`**, the managed collection: who, which tool,
+kind, provider, model, tokens in/out (when the provider said), credits,
+outcome, refusal code, latency, when. The **prompt and answer** ride the row
+only when the owner switches *record calls* on for that tool — off by
+default. A person reads their own (`g.ai.calls()`), the owner reads by app
+in the back office, erasure removes a person's rows.
 
 | Method | Signature | Returns |
 |--------|-----------|---------|
-| `ai.chat` | `(body: object, options?: { tool?: string; provider?: "openai" \| "anthropic" \| "google"; signal?: AbortSignal })` | `Promise<Response>` — the fetch `Response`, untouched: the provider's status, headers and body, streaming intact. A non-2xx from the provider is returned as-is (not thrown) — an answer carrying `x-gemmein-credits-remaining` passed the spend and is the provider's; a Gemmein refusal throws `GemmeinError` |
-| `ai.text` | `(body: object, options?: { tool?: string; provider?: …; signal?: AbortSignal })` | `Promise<string>` — a non-stream call collected to one string, whichever provider answered (openai `choices[0].message.content`; anthropic `content[].text` joined; google `candidates[0].content.parts[].text` joined); a provider's non-2xx throws `provider_error` with the provider's status and message |
+| `ai.run` | `(tool: string, inputs?: Record<string, string \| number \| boolean>, options?: { stream?: boolean; signal?: AbortSignal })` | `Promise<Response>` — the tool's provider's own answer, untouched (SSE when `stream`). A non-2xx from the provider is returned as-is; a Gemmein refusal throws `GemmeinError` |
+| `ai.runText` | `(tool: string, inputs?: …, options?: { signal?: AbortSignal })` | `Promise<string>` — a non-stream run collected to one string, whichever provider answered; a provider's non-2xx throws `provider_error` |
+| `ai.calls` | `(options?: { limit?: number; before?: string })` | `Promise<{ calls: AiCallRecord[]; nextCursor: string \| null }>` — the signed-in person's own calls, newest first |
+| `ai.chat` | `(body: object, options?: { tool?: string; provider?: "openai" \| "anthropic" \| "google"; signal?: AbortSignal })` | `Promise<Response>` — RAW (needs the owner's switch): the fetch `Response`, untouched |
+| `ai.text` | `(body: object, options?: { tool?: string; provider?: …; signal?: AbortSignal })` | `Promise<string>` — RAW, non-stream, one string |
+
+- **The tool file.** `name` (the file name; fixed once created), `label`,
+  `provider`, `model` (pin it — a composed call needs one; with none, the
+  owner's first allowed model, else the provider's small default),
+  `credits`, `requires`, `enabled`, `bounds`, plus the implementation:
+  `kind` (`chat`, the first), `instructions` (the system turn, ≤ 20,000
+  chars — never leaves the server), `promptTemplate` (the user turn with
+  `{{input}}` placeholders naming declared inputs; ≤ 20,000; absent = the
+  inputs rendered one per line as `name: value`), `inputs` (≤ 20 of
+  `{ name, type: text|number|boolean, required?, maxLength? }` — names
+  1–40 lowercase letters/digits/underscores, starting with a letter; a
+  text input ≤ 4,000 chars
+  unless it says, ≤ 20,000), `recordCalls` (off by default). A tool with
+  neither a template nor inputs composes nothing: `409 tool_incomplete`.
+- **Inputs are checked by name** before any spend: an unknown input, a
+  missing required one, a wrong type or a value over its cap is
+  `400 invalid_inputs` — the message names the input and the rule. The run
+  body is `{ inputs, stream? }` and at most 64 KB.
+- **Composition** per provider: OpenAI `messages` (system + user),
+  `max_completion_tokens`; Anthropic `system` + `messages`, `max_tokens`;
+  Google `systemInstruction` + `contents`, `generationConfig.maxOutputTokens`.
+  The output ceiling is `bounds.maxOutputTokens` or 4,096 — a composed
+  call is never "as long as the model likes". `bounds.stream: false`
+  forces a non-stream answer.
 
 - `tool` names an `ai_tools` row by its slug; omit it for the default tool.
   An unknown name is `404 unknown_tool`; a tool the owner switched off is
@@ -397,7 +446,7 @@ calls the provider directly.
   OpenAI chat completions, Anthropic messages, Google generateContent. Its
   `model` field, when present, must match `^[A-Za-z0-9._:-]{1,80}$`; Google
   needs it (it rides the URL); when the owner lists allowed models (up to
-  20 — the Keys room's test call uses the first), any other answers
+  20 — the AI tools page's test call uses the first), any other answers
   `403 model_not_allowed`.
 - `provider` is optional when one key is configured and required when more
   than one is (`400 provider_required`); a named tool fixes its own
@@ -418,31 +467,46 @@ calls the provider directly.
 - Limits: 20 calls per person per minute (`429 ai_capped`, `resetAt`), 256 KB
   body by default (`413 payload_too_large`, unless a tool sets a smaller
   `bounds.maxBodyBytes`) nested at most 32 levels (`400 invalid_body`),
-  170 s in all and, on a stream, 10 s to the first response headers. Every
+  170 s in all and, on a stream, 10 s to the first response headers. A
+  tool's `credits` are 1–10,000; `bounds.maxOutputTokens` is 1–100,000,
+  4,096 when the tool sets none. Every
   `/ai/chat` call counts toward the app's `api_requests` band like any other
   request.
 
 ```ts
-const res = await g.ai.chat({
-  model: "gpt-4o-mini", stream: true,
-  messages: [{ role: "user", content: text }]
-}, { tool: "deep-research" })
+// gemmein/ai/tools/deep-research.json
+// { "label": "Deep Research", "provider": "openai", "model": "gpt-4o", "credits": 20,
+//   "requires": "access:pro-max",
+//   "instructions": "You are a careful research assistant. Answer with sources.",
+//   "promptTemplate": "Research this for a {{audience}} reader:\n\n{{question}}",
+//   "inputs": [{ "name": "question", "type": "text", "required": true, "maxLength": 2000 },
+//              { "name": "audience", "type": "text" }],
+//   "bounds": { "maxOutputTokens": 4000 } }
+
+const res = await g.ai.run("deep-research", { question: text, audience: "beginner" }, { stream: true })
 for await (const chunk of res.body) render(chunk)      // the provider's SSE, byte for byte
 
-const answer = await g.ai.text({ messages: [{ role: "user", content: text }] }, { tool: "deep-research" })
+const answer = await g.ai.runText("deep-research", { question: text })
+const { calls } = await g.ai.calls()                     // the person's own history
+
+// RAW — only behind the owner's "raw calls" switch for that provider key:
+const raw = await g.ai.chat({ model: "gpt-4o-mini", stream: true, messages: [{ role: "user", content: text }] })
 ```
 
 | code | status | meaning · do |
 |------|--------|--------------|
+| `raw_calls_off` | 403 | The browser may not compose provider requests for this provider — call a named tool with `g.ai.run`, or the owner switches raw calls on for the key on the AI tools page |
+| `invalid_inputs` | 400 | An input is unknown, missing, the wrong type or over its cap — the message names it |
+| `tool_incomplete` | 409 | The tool composes nothing (no template, no inputs) — give it one; the owner's or the file's fix |
 | `unknown_tool` | 404 | No AI tool by this name in this environment — check the slug or the environment |
 | `tool_disabled` | 403 | The owner switched this tool off — turn it on, or use another |
 | `entitlement_required` | 403 | The tool's `requires` names a plan or product this person lacks — the message names it |
 | `model_pinned` | 403 | This tool's model is fixed — leave `model` out of the body |
-| `provider_not_configured` | 409 | Creating or updating a tool: no key is set for that provider yet — add one on the Keys page first |
+| `provider_not_configured` | 409 | Creating or updating a tool: no key is set for that provider yet — add one on the AI tools page first |
 | `too_many_tools` | 409 | This environment already holds 50 AI tools — delete one before adding another |
 | `invalid_tool` | 400 | Creating or updating a tool with a bad field — the message names which one and its rule |
 | `credits_exhausted` | 402 | The person's balance is below the tool's price — the message names the tool, the price and the balance ("Deep Research costs 20 credits. You have 7.", singular for 1). Show the pack |
-| `ai_not_configured` | 409 | No provider key on this app and environment — the owner pastes one in the Keys room |
+| `ai_not_configured` | 409 | No provider key on this app and environment — the owner pastes one on the AI tools page |
 | `provider_required` | 400 | More than one provider key is set — pass `provider` |
 | `model_not_allowed` | 403 | The owner's allowlist names the models this app may call; the message lists them (only for a tool with no pinned model) |
 | `ai_capped` | 429 | 20 calls per person per minute — wait for `resetAt` |
@@ -451,8 +515,9 @@ const answer = await g.ai.text({ messages: [{ role: "user", content: text }] },
 | `session_required` | 401 | No signed-in person — sign in first |
 | `scope_denied` | 403 | A secret key called the route — the route is for the browser; a server calls the provider directly |
 | `provider_unreachable` | 502 | The provider did not answer before the first byte — nothing was charged (the tool's credits are refunded); retry |
-| `provider_error` | the provider's | `g.ai.text` only (client-side): the provider's own non-2xx, its message in `err.message` |
-| `ai_test_capped` | 429 | The Keys room's test call — one a minute per app |
+| `provider_error` | the provider's | `g.ai.text` and `g.ai.runText` (client-side): the provider's own non-2xx, its message in `err.message` |
+| `invalid_response` | 0 (client-side) | `g.ai.text` and `g.ai.runText`: a non-stream answer with no text to lift out — for a streaming body read the stream with `g.ai.chat` or `g.ai.run` |
+| `ai_test_capped` | 429 | The AI tools page's test call — one a minute per app |
 
 `gemmein dev` answers a fake provider without a key (header `x-gemmein-ai:
 fake`, an echo stream), so the loop runs locally; set
@@ -569,8 +634,10 @@ provider's webhook arriving, a clock, a record changing — and one to ten of
 Gemmein's **own** verbs, run in order: write a record, grant or revoke access,
 email the person, call your URL. Gemmein runs no code of yours inside one;
 compute lives on your host, behind `call_url`. The definition is a JSON file
-your AI writes; the owner's dashboard shows it read-only with its receiver URL,
-its secrets (shown once), every event with each action's result, and a replay
+your AI writes, or the owner writes in the dashboard, which creates and edits
+it too, pauses, resumes, rotates and deletes it, and shows where it came from
+("from file, synced <when>" / "edited here <when>"), its receiver URL, its
+secrets (shown once), every event with each action's result, and a replay
 button. There is no SDK method: the surface is the file and the dashboard.
 Stripe stays built in; any provider that signs its webhooks — GoCardless, Paddle,
 Lemon Squeezy among them — drives access the same way through a relay, and the
@@ -760,7 +827,16 @@ receiver's local URL), schedules and data changes with the same runner and
 prints `RELAY · <name> · <trigger> · <n actions> · ok|failed`;
 `npx gemmein sync` carries the files to the cloud app's development
 environment with the collections — contract, never data; the cloud mints its
-own secrets.
+own secrets. After go-live, `npx gemmein sync --live` carries relays and AI
+tools into production: it asks for a **sync key** (Secret keys → production →
+Sync key — step-up to mint, lives one hour, shown once, never saved by the
+CLI), prints what would change, waits for the word `live`, never deletes, and
+refuses collections (they move by promotion). A row edited in the dashboard
+since the last sync is asked about, per item (`--overwrite` answers yes);
+every relay says where its definition came from — from file, or edited in the
+dashboard — and when. A relay's name is fixed once created: the receiver URL
+is built from it, so a rename is refused (`invalid_definition`) — create the
+new one, delete the old in the dashboard once the provider has moved.
 
 ---
 
@@ -793,7 +869,10 @@ line; a wrong-but-well-formed name surfaces as `unknown_collection` and exits
 
 ### `gemmeinServer(sk).testSession(email) → { token, expiresAt, user }`
 **Dev only** — throws `test_session_forbidden_live` on an `sk_live` key, and
-the server refuses it on a live environment too. Pass the `token` to
+the server refuses it on a live environment too. Test **people** only: a
+server key is refused the account owner's or an admin's email
+(`scope_denied`) — the app's CLI key (Setup page) is the credential that
+acts as the founder, and it is the only key that links or syncs. Pass the `token` to
 `gemmein(pk, { tokenStore })` to act as that user. Dev and live enforce the
 *same* rules, so what is proven in dev holds in live.
 
@@ -844,6 +923,9 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `entitlement_required` | 403 — signed in, but not on a plan (or holding a product) this collection is unlocked by; `err.requires` is that plan's key (`access:<slug of its name>`) | show your upgrade screen and send them to checkout — the one 403 that succeeds later |
 | `not_found` | record you can't see (existence not leaked) | treat as absent |
 | `denied` | 401 (sign in first) or 429 (rate limit — see `resetAt`) | re-auth or wait+retry |
+| `invalid_body` | 400 — the request body is not a JSON object (an array or a bare value was sent) | send an object |
+| `missing_params` | 400 — a required field is absent or EMPTY; the message names it (`missing email`, `missing code`). The SDK passes what you give it, so a blank form field reaches the API as missing | check the field before calling — a blank email is not a sign-in attempt |
+| `field_too_long` | 400 — a sign-in field (`email`, `code`, the test-session fields) is over 500 characters; the message names the field | shorten it |
 | `conflict` | a keyed create / floor / stale `ifVersion` | it's the mechanism — tell the user it's taken |
 | `html_not_allowed` | HTML in a community/addressed/direct field | store plain text |
 | `invalid_publish` | `{ published }` on a non-public rule | drop it |
@@ -861,24 +943,25 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `unknown_plan` | no plan by that name | use a name from the list in the message |
 | `plan_not_purchasable` | tried to check out the free default plan | nothing to buy — gate on the paid plan's name |
 | `invalid_expand` | `expand` on a field/rule with no link shape | join in memory instead (private/public_read/admin_write have no links) |
-| `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes) | scope the key to that collection, or use the right surface |
+| `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes); a server key asked to sign in as the account owner or an admin, or to link/sync; a sync key asked for anything but relays and AI tools | scope the key to that collection, or use the right surface — linking and dev sync use the CLI key (Setup), production sync a Sync key (Secret keys → production) |
+| `secret_key_expired` (403) | a sync key past its hour — the message names the instant | mint a new Sync key (Secret keys → production) and run `npx gemmein sync --live` again |
 | `unsupported_file_type` (415) | upload isn't an allowed type | images (JPEG/PNG/WebP/GIF/HEIC) or documents (PDF/ZIP/EPUB) |
 | `invalid_key` | a keyed create's `key` breaks the charset/length law — or `spendCredits`' `key` is not text of up to 200 chars | 1-120 chars of letters, numbers, `: _ . @ / -` (a create); text ≤ 200 (a spend) |
 | `invalid_amount` / `invalid_reason` (400) | `spendCredits`: `amount` outside 1..10,000, or `reason` missing / over 200 chars | fix the field the code names |
 | `dedupe_conflict` (409) | `spendCredits`: the `key` already names a different movement (another kind or another person) | a key is one movement — reuse it only to retry that same one |
 | `credits_ceiling` (409) | a credit would carry the balance past 1,000,000,000 (a comp, a pack, a relay grant) — nothing was added | the balance is at its most |
 | `invalid_body` (400) | on `g.ai.chat`: the body is not the provider's JSON request object, or is nested deeper than 32 levels | send the provider's own request object |
-| `provider_error` (client-side, the provider's status) | `g.ai.text`: the provider answered a non-2xx; `err.message` is the provider's own reason | read it — the credit was refunded when the provider failed before its first byte |
-| `ai_test_capped` (429) | the Keys room's test call — one a minute per app | wait a minute |
+| `provider_error` (client-side, the provider's status) | `g.ai.text` and `g.ai.runText`: the provider answered a non-2xx; `err.message` is the provider's own reason | read it — the credit was refunded when the provider failed before its first byte |
+| `ai_test_capped` (429) | the AI tools page's test call — one a minute per app | wait a minute |
 | `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
-| `invalid_response` (client-side, status 0) | the server answered 200 to `verifyEmailCode` without a session token — a proxy or mock in the path, not Gemmein | check `apiUrl` and anything rewriting responses; the call is safe to retry |
+| `invalid_response` (client-side, status 0) | the server answered 200 to `verifyEmailCode` without a session token — a proxy or mock in the path, not Gemmein; or `g.ai.text` / `g.ai.runText` got a non-stream provider answer with no text to lift out | check `apiUrl` and anything rewriting responses; the call is safe to retry — for AI, read the stream with `g.ai.chat` or `g.ai.run` |
 | `authentication_required` (401) | checkout/subscription/pay without a signed-in user | sign the user in first |
 | `plan_has_no_link` (409) | the paid plan has no Payment Link pasted yet | ask the owner to paste it in their dashboard |
 | `product_not_sellable` (409) | `g.payments.buy` on a product sold via a relay or not yet — there is no Payment Link to open | tell the buyer how the product is sold, or ask the owner to wire a road |
 | `relay_missing` (400) | saving a relay action (or a product's `sold.relay`) names a relay that does not exist in this environment | create that relay first, or name one that exists |
 | `account_suspended` (403) | the app owner's account is suspended (billing) | the owner fixes payment at app.gemmein.com |
 | `credits_exhausted` (402) | the person's balance is below the spend — the message carries the balance ("this person has {balance} credits — the spend needs {amount}") | show the pack; never retry the same spend |
-| `ai_not_configured` (409) | no provider key on this app and environment | the owner pastes one in the Keys room |
+| `ai_not_configured` (409) | no provider key on this app and environment | the owner pastes one on the AI tools page |
 | `provider_required` (400) | more than one provider key is set and the call named none | pass `provider` |
 | `model_not_allowed` (403) | the owner's allowlist does not name this model | use one the message lists |
 | `ai_capped` (429) | 20 AI calls per person per minute | wait for `resetAt` |

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.8.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,16 +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 a credit,
- * adds the owner's key, forwards, and passes status and bytes back. Pass
- * `tool` (W9.3b) to run a named, owner-priced-and-gated operation 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.
+ * 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) {
@@ -411,7 +419,10 @@ 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) ·
@@ -457,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.8.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.8.0";
+export declare const CLIENT_INFO = "gemmein-sdk/0.9.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -387,6 +387,23 @@ 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. Refused
@@ -396,7 +413,10 @@ export type AiChatOptions = {
     /** 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. */
+     *  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. */
@@ -433,16 +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 a credit,
- * adds the owner's key, forwards, and passes status and bytes back. Pass
- * `tool` (W9.3b) to run a named, owner-priced-and-gated operation 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.
+ * 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;
@@ -452,7 +480,10 @@ 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) ·
@@ -472,6 +503,63 @@ export declare class AiClient {
      * 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