@argentic/chest-sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,10 +1,12 @@
 # Chest SDK
 
 `@argentic/chest-sdk` is what a server tool (tool contract v2) embeds to talk
-with its Chest: the member the Chest asserts on a request, the other members
+with its Chest: the member the Chest asserts on a request, the Chest itself
+(its organization, time zone and language), the other members
 who have the tool, the address of the tool's own database, its private
 files, the badges and notifications it shows members inside the Chest, the
-events of its members' lifecycle — and, for the tool's tests, a fake Chest. The SDK has no dependency: it
+events of its members' lifecycle, AI models through the Chest — and, for the
+tool's tests, a fake Chest. The SDK has no dependency: it
 only imports `node:*`.
 
 ```sh
@@ -16,31 +18,35 @@ Node 22 or later. ESM only, compiled JavaScript with its type declarations.
 ## Imports
 
 Each module is its own subpath and pulls in nothing else; the root gives them
-all, with the files, members, notifications and events APIs as the
-namespaces `files`, `members`, `notifications` and `events` (the testing
-module is not in the root).
+all, with the files, members, notifications, events and ai APIs as the
+namespaces `files`, `members`, `notifications`, `events` and `ai` (the
+testing module is not in the root).
 
 | Import | Gives |
 |---|---|
-| `@argentic/chest-sdk/member` | `member(request)`, type `Member`: the member of a request on the team host of a server tool, read from the `Chest-Member` assertion and verified; `null` without a valid assertion. `memberIdPattern`, `groupIdPattern`: the grammars of the identifiers (`mbr_…`, `grp_…`) |
+| `@argentic/chest-sdk/member` | `member(request)`, type `Member`: the member of a request on the team host of a server tool, with the language the Chest speaks to them and the zone they work in, read from the `Chest-Member` assertion and verified; `null` without a valid assertion. `memberIdPattern`, `groupIdPattern`, `languagePattern`, `timeZonePattern`: the grammars of the identifiers (`mbr_…`, `grp_…`), of a language and of a zone |
+| `@argentic/chest-sdk/chest` | `chest`, type `Chest`: the Chest the tool runs in — `chest.organization.name`, `chest.timeZone`, `chest.language`, `chest.today()` —, the same for every member, on a request or outside one |
 | `@argentic/chest-sdk/members` | `list`, `get`, `lookup`, `groups.list`, `forget`, types `MemberPage`, `Lookup`, `FormerMember`, `Group`: the members who have the tool (capability `members`, their addresses with `members.email`) |
 | `@argentic/chest-sdk/notifications` | `notify`, `withdraw`, `badge.set`, `badge.setMany`, types `Notice`, `Delivery`, `BadgeCount`, `BadgeWrite`: counters on the tool's tile and items in members' inboxes, inside the Chest (capability `notifications`) |
 | `@argentic/chest-sdk/events` | `handle`, `verify`, `acknowledgeErasure`, `memorySeen`, `erasureIdPattern`, types `ChestEvent`, `MemberUpdated`, `AccessRevoked`, `MemberRemoved`, `MemberErased`, `MemberChange`, `Handlers`, `Seen`: the events of the members' lifecycle the Chest posts to the tool's `/chest-events` (`"receives": ["member.*"]`), verified, deduplicated by id, and the acknowledgment of an erasure |
+| `@argentic/chest-sdk/ai` | `chat`, `embed`, `models`, `usage`, types `Alias`, `Provider`, `ChatMessage`, `ChatTool`, `ToolChoice`, `ResponseFormat`, `ChatOptions`, `ChatResult`, `ChatChunk`, `ToolCall`, `ToolCallDelta`, `Usage`, `EmbedOptions`, `Embeddings`, `AiModel`, `AiUsage`: AI models through the Chest, on the owner's connectors, metered against the tool's monthly cap (capability `ai`) |
 | `@argentic/chest-sdk/database` | `databaseUrl()`: the address of the tool's own PostgreSQL database (capability `database`) |
 | `@argentic/chest-sdk/files` | `put`, `get`, `stat`, `list`, `move`, `delete`, `url`, `uploadUrl`, types `FileObject`, `FileData`, `FilePage`: the tool's private files (capability `files`), kept by the Chest, a 15-minute signed link to one (or to its thumbnail), and uploads straight from a member's browser |
-| `@argentic/chest-sdk/errors` | `ChestError` (`code`, `status`), `CapabilityNotGranted` (403), `TooLarge` (413), `QuotaExceeded` (429), `RateLimited` (429), `Unavailable` (503): what the SDK throws when the Chest does not give what a tool asks |
-| `@argentic/chest-sdk/testing` | `signAssertion`, `withMember`, `fakeChest`, types `FakeChest`, `FakeChestOptions`, `FakeGroup`, `FakeFile`, `FakeNotification`, `FakeEvent`: for the tool's own tests only |
-| `@argentic/chest-sdk` | all of the above but `testing`; `files`, `members`, `notifications` and `events` as namespaces |
+| `@argentic/chest-sdk/errors` | `ChestError` (`code`, `status`), `CapabilityNotGranted` (403), `TooLarge` (413), `QuotaExceeded` (429), `RateLimited` (429), `Unavailable` (503), and for AI `AiCapReached` (402), `AiModelNotAllowed` (403), `AiRefused` (422), `AiUnavailable` (502, 503), type `AiUnavailableReason`: what the SDK throws when the Chest does not give what a tool asks |
+| `@argentic/chest-sdk/testing` | `signAssertion`, `withMember`, `fakeChest`, types `AssertionOptions`, `FakeChest`, `FakeChestOptions`, `FakeGroup`, `FakeFile`, `FakeNotification`, `FakeEvent`, `FakeAi`, `FakeAiModel`, `FakeAiReply`, `FakeAiCall`: for the tool's own tests only |
+| `@argentic/chest-sdk` | all of the above but `testing`; `files`, `members`, `notifications`, `events` and `ai` as namespaces |
 
 ```ts
 import { member } from "@argentic/chest-sdk/member";
+import { chest } from "@argentic/chest-sdk/chest";
 import { databaseUrl } from "@argentic/chest-sdk/database";
 import * as files from "@argentic/chest-sdk/files";
 import * as members from "@argentic/chest-sdk/members";
 import * as notifications from "@argentic/chest-sdk/notifications";
 import * as events from "@argentic/chest-sdk/events";
+import * as ai from "@argentic/chest-sdk/ai";
 import { CapabilityNotGranted } from "@argentic/chest-sdk/errors";
-// or: import { member, databaseUrl, files, members, notifications, events } from "@argentic/chest-sdk";
+// or: import { member, chest, databaseUrl, files, members, notifications, events, ai } from "@argentic/chest-sdk";
 ```
 
 Types refer to `node:http` (`IncomingMessage`): a TypeScript project needs
@@ -50,7 +56,7 @@ Types refer to `node:http` (`IncomingMessage`): a TypeScript project needs
 ### Next.js
 
 The SDK runs on the server only — it reads the tool's environment
-(`CHEST_TOKEN`, `DATABASE_URL`, `CHEST_API`) and uses Node built-ins. Import it
+(`CHEST_TOKEN`, `DATABASE_URL`, `CHEST_API`, `CHEST_TIME_ZONE`…) and uses Node built-ins. Import it
 in route handlers, server components or server actions, never in a
 `"use client"` module. Webpack and Turbopack resolve the
 compiled package with no configuration (no `transpilePackages`):
@@ -70,7 +76,7 @@ export function GET(request: Request) {
 A v2 tool is an ordinary web server in a container without network, run by
 its Chest. The Chest's front is the only one to reach it; the tool reaches only
 what its launcher gives it on `127.0.0.1` (its database, the Chest's API for
-its files, its members and its notifications), and the Chest posts it the
+its files, its members, its notifications and AI), and the Chest posts it the
 events it receives on `/chest-events`, through the same launcher. Rights come
 from the Chest — the signed member, the capabilities approved for the
 version — and the Chest enforces them even outside the SDK:
@@ -83,7 +89,8 @@ is described in the Chest repository, `docs/architecture.md`.
 A v2 tool is an ordinary web server; on its team host, the Chest relays
 `/chest` and everything below it with the `Chest-Member` header of the
 signed-in member. `member(request)` accepts a Node request (`IncomingMessage`)
-or a Web `Request` and returns:
+or a Web `Request` and returns a `Member`, the type the `members` API
+answers too:
 
 ```ts
 type Member = {
@@ -96,6 +103,8 @@ type Member = {
   isAdmin: boolean;      // owner or admin of the Chest
   isBuilder: boolean;    // builder of this tool
   groups: string[];      // "grp_…": the groups that give the member this tool
+  language: string;      // "en", "fr"…: the language the Chest speaks to this member
+  timeZone: string;      // "America/New_York": the zone the member works in
   email?: string;        // only with the capability "members.email"
 };
 ```
@@ -105,10 +114,13 @@ assertion there and strips a client's), or for any assertion that is not
 exactly its own. Checks: compact JWS, header exactly
 `{"alg":"HS256","typ":"JWT"}`, HMAC-SHA256 signature compared in constant time
 under the key HMAC-SHA256("Chest-Member v2") of the text of `CHEST_TOKEN` —
-the Chest's derivation; the label changes with the shape of the claims, so an
-assertion of another shape is refused rather than misread —, `aud` equal to
+the Chest's derivation; the label changes when a claim changes meaning or
+goes, so an assertion of another shape is refused rather than misread, and
+stays when a claim is added —, `aud` equal to
 `CHEST_TOOL`, `iat` and `exp` within 5 s, the shape of each claim (`sub` an
-`mbr_` identifier, `groups` `grp_` identifiers; an unknown claim is ignored). Without
+`mbr_` identifier, `groups` `grp_` identifiers, `language` a primary tag of
+2 or 3 lowercase letters, `time_zone` a zone of `timeZonePattern`; an
+unknown claim is ignored). Without
 `CHEST_TOKEN` or `CHEST_TOOL`, nobody is a member. The function never throws
 for what a request carries.
 
@@ -127,6 +139,72 @@ member among those the manifest declares. Only the Chest's front reaches the
 container: the signature is a second defence; business rules (who writes
 what) remain the tool's.
 
+`language` is the member's own language in the Chest, else the Chest's
+default: a BCP 47 primary tag among those the product speaks (`en`, `fr`
+today; the SDK accepts any, so a language added to the Chest needs no new
+SDK). The tool's private part (`/chest`) speaks it — to this member, on every
+request — and offers no language switch of its own; only its public parts,
+where nobody is signed in, keep their own switch. The members API answers
+it too: a notification or an email to another member is written in *their*
+language (`members.get(id).language`), not in the sender's. A tool that does not
+speak that language uses its own default. `timeZone` is the zone the member
+works in: the one they chose in their profile, else the one their browser
+is in, else the Chest's. The members API answers it too, so a tool reminds
+each member at their own hour. What is the same for every member — the
+organization, the company's time zone — is not the member's: it is the
+Chest's (below).
+
+### Times: store in UTC, decide in the Chest's zone, show in the member's
+
+| What | Zone |
+|---|---|
+| An instant (created, due at, sent at) | stored as UTC: `timestamptz` in PostgreSQL, `Date` in code |
+| “Today”, “this week”, a deadline's day, business hours, working days | the company's: `chest.timeZone`, `chest.today()` (the database's `current_date` is the same) |
+| A time or a date shown to a member, a personal reminder's hour | theirs: `member(request).timeZone`, or `members.get(id).timeZone` outside their request |
+
+```ts
+const who = member(request)!;
+const due = await sql`select * from tasks where due_on = ${chest.today()}`; // the company's day
+const shown = new Intl.DateTimeFormat(who.language, { timeZone: who.timeZone, dateStyle: "medium", timeStyle: "short" }).format(task.remindAt);
+```
+
+## `chest` — the Chest the tool runs in
+
+```ts
+import { chest } from "@argentic/chest-sdk/chest";
+
+chest.organization.name; // "Acme SAS": the organization the Chest is of, as its owner wrote it
+chest.timeZone;          // "Europe/Paris": an IANA zone, "UTC" until the owner sets one
+chest.language;          // "fr": the Chest's own language (a member's is member(request).language)
+chest.today();           // "2026-09-30": the date now in the Chest's zone (or chest.today(at))
+```
+
+The Chest gives these to every tool in its environment at each start
+(`CHEST_ORGANIZATION`, `CHEST_TIME_ZONE`, `CHEST_LANGUAGE`), and starts every
+tool again when its owner changes one in Settings → General — the tool never
+asks its own admin for the company's name or zone. They are there outside a
+request too: a scheduled job, a start-up task, an export. No capability is
+needed: nothing here is more than what the Chest's pages show its members.
+
+- `organization.name` is plain text of 2 to 80 characters: show it in a
+  header, a document or an email, never as HTML.
+- `timeZone` is the day of “due today” and the hour of a reminder. The Chest
+  also makes it the `TimeZone` of the tool's database sessions: there,
+  `current_date`, `now()::date` and a `timestamptz` shown as text are in the
+  Chest's zone. A session may set its own (`SET TIME ZONE`), for itself.
+- `language` is the language of what the tool writes for no one in
+  particular: a public page before the visitor chooses, an export's default.
+  A page of `/chest` speaks `member(request).language` instead.
+- `today(at?)` is `YYYY-MM-DD` in the Chest's zone, for now or for an instant
+  (`Date` or milliseconds): compare it with dates your database keeps as
+  `date`, never with `new Date().toISOString().slice(0, 10)`, which is UTC's.
+
+Each value is read from the environment at each access, and checked: outside a
+Chest (a development server without the variables), or for a value the Chest
+never gives, reading it throws a `ChestError` with the code `not_in_chest` —
+a wrong zone read silently is exactly what this module exists to prevent. In
+tests, `fakeChest({chest: {organization, timeZone, language}})` sets them.
+
 ## `members` — who has the tool
 
 A v2 tool that declares `"capabilities": ["members"]` (approved like a
@@ -340,6 +418,115 @@ export async function POST(request: Request) {
   `ChestError` `erasure_not_found` (404: an erasure this tool was not told of)
   or `invalid_id` (400), `CapabilityNotGranted` (403), `Unavailable`.
 
+## `ai` — AI models through the Chest
+
+A v2 tool that declares the `ai` capability calls AI models through its
+Chest. The Chest's owner connects OpenRouter with the company's own key;
+the tool calls models by four **aliases**: `default`, `fast`, `smart`,
+`embedding`, each led by the Chest to a model it chose (the owner may choose
+another for `default`). The tool names an alias, never a provider's model:
+the model changes for the whole Chest without touching code. The tool never
+holds a key; the Chest meters every call against the tool's monthly cap.
+
+```jsonc
+// chest.json
+{
+  "capabilities": ["ai"],
+  "ai": { "monthly": 20, "models": ["default", "embedding"], "purpose": "Summarises support tickets" }
+}
+```
+
+| Key | Default | |
+|---|---|---|
+| `monthly` | 5 | Whole euros a month, 1 to 1,000: what the tool asks; the owner's cap replaces it and may be changed at any time |
+| `models` | `["default"]` | 1 to 4 of `default`, `fast`, `smart`, `embedding`: the only aliases the tool may call |
+| `purpose` | required | 1 to 120 characters, shown at approval: “Uses AI models through the Chest, up to €20 a month” |
+
+```ts
+import * as ai from "@argentic/chest-sdk/ai";
+
+const r = await ai.chat({
+  model: "default",
+  messages: [{ role: "system", content: "Summarise in two sentences." }, { role: "user", content: ticket.text }],
+  maxTokens: 300,                 // 1 to 128,000; 4,096 when not said
+  member: who.id,                 // optional: attribution in the Chest's usage log
+});
+r.text;                           // "" when the model only called tools
+r.usage;                          // { input, output, cached, cost } — cost in estimated euros
+
+// Streamed: pieces as they come; breaking out of the loop ends the call.
+for await (const chunk of ai.chat({ model: "fast", messages, stream: true, signal })) {
+  write(chunk.text);              // chunk.toolCalls, chunk.finishReason, then chunk.usage last
+}
+
+// Tools: the model asks, the tool runs them and answers.
+const step = await ai.chat({ model: "smart", messages, tools: [{ type: "function", function: { name: "lookup", parameters: schema } }] });
+messages.push(step.message);
+for (const call of step.toolCalls) messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(await run(call.name, JSON.parse(call.arguments))) });
+
+const { embeddings } = await ai.embed({ model: "embedding", input: ["first text", "second text"] }); // 1 to 256 texts
+const mapped = await ai.models();  // [{ alias, model, provider, input, output }] — USD per million tokens
+const month = await ai.usage();    // { month: "2026-09", spent, cap, resetsAt }
+```
+
+- **`chat(options)`** takes the OpenAI Chat Completions request in camelCase:
+  `model`, `messages`, `maxTokens`, `temperature`, `topP`, `stop`, `tools`,
+  `toolChoice`, `responseFormat`, `parallelToolCalls`, `seed`,
+  `reasoningEffort`, plus `member`, `stream` and `signal`. Messages, tools and
+  response formats keep the OpenAI shape (images in `content` parts too); the
+  Chest translates them for each provider and never runs a tool. Without
+  `stream` it returns `Promise<ChatResult>` `{text, message, toolCalls,
+  finishReason, model, usage}` — `message` is the assistant's message to add
+  to the conversation, `toolCalls` are `{id, name, arguments}` with the
+  arguments as JSON text, `model` is the provider's model. With
+  `stream: true` it returns an `AsyncIterable<ChatChunk>` `{text, toolCalls?,
+  finishReason?, usage?}`: tool calls come in pieces (`{index, id?, name?,
+  arguments?}`: join the `arguments` of the same `index`), the usage in the
+  last chunk.
+- **Bounds**: a request body of 10 MiB (images included), 16 MiB of answer, a
+  call ends after 10 minutes (streamed or not); 60 requests a minute and 8
+  streams at once per tool (`RateLimited`). An aborted `signal` throws its
+  reason.
+- **The cap never overshoots**: before a call the Chest reserves its worst
+  case (input and `maxTokens`) against the tool's cap and the Chest's; a call
+  that does not fit is refused before anything is spent. Keep `maxTokens` to
+  what the answer needs.
+- **`embed({model, input, dimensions?, member?})`** gives one vector per text,
+  in the order given, and the input tokens and cost.
+- **`models()`** gives the aliases the tool declared that the owner mapped,
+  with their model, provider and prices; **`usage()`** the tool's month:
+  estimated euros spent, the cap in force, and when the month resets.
+
+**AI can stop at any time** — the month's budget spent, no connector, the
+provider down. Keep the tool usable without it:
+
+```ts
+import { AiCapReached, AiUnavailable } from "@argentic/chest-sdk/errors";
+
+let summary: string | null = null;
+try {
+  summary = (await ai.chat({ model: "default", messages, maxTokens: 300 })).text;
+} catch (error) {
+  if (!(error instanceof AiCapReached || error instanceof AiUnavailable)) throw error;
+  // summary stays null: show "AI features are paused" and keep the page working
+}
+```
+
+| Error | Code, status | When |
+|---|---|---|
+| `AiCapReached` | `cap_reached` 402 | The tool's (`scope: "tool"`) or the Chest's (`scope: "chest"`) monthly cap is spent, until `resetsAt` |
+| `AiUnavailable` | `no_connector` 503, `provider_key_invalid` 502, `provider_unavailable` 503 | No connector behind the alias, the provider refused the connector's key, or failed (`reason`) |
+| `AiModelNotAllowed` | `model_not_allowed` 403 | An alias the tool did not declare in `models` (the SDK refuses any other name before sending) |
+| `CapabilityNotGranted` | `capability_not_granted` 403 | The version does not hold `ai`, or it was not approved |
+| `AiRefused` | `content_refused` 422 | The provider's moderation refused the content |
+| `RateLimited` | `rate_limited` 429 | 60 requests a minute or 8 streams at once |
+| `TooLarge` | `too_large` 413 | A body beyond 10 MiB, or a context beyond the model's |
+| `ChestError` | `invalid_body`, `invalid_request` 400 | A malformed request (the SDK refuses most before sending), or parameters the provider rejected (its message in the error's) |
+| `Unavailable` | `unavailable` 503 | The Chest not reached, or an answer that is not its own; in a stream, the stream cut |
+
+An error in the middle of a stream is thrown where it comes, after the chunks
+before it.
+
 ## `databaseUrl()` — database of a server tool
 
 A v2 tool that declares `"capabilities": ["database"]` in its `chest.json`
@@ -484,8 +671,8 @@ version keeps them.
 ```ts
 import { fakeChest, signAssertion, withMember } from "@argentic/chest-sdk/testing";
 
-const camille = { id: "mbr_k2qhx4mzc7v3b6nfp5r2t7w4ya", firstName: "Camille", lastName: "Martin", name: "Camille Martin", photo: null, role: "editor", isAdmin: false, isBuilder: false, groups: [] };
-const chest = await fakeChest({ members: [camille], capabilities: ["members", "files", "notifications"] });
+const camille = { id: "mbr_k2qhx4mzc7v3b6nfp5r2t7w4ya", firstName: "Camille", lastName: "Martin", name: "Camille Martin", photo: null, role: "editor", isAdmin: false, isBuilder: false, groups: [], language: "fr", timeZone: "Europe/Paris" };
+const chest = await fakeChest({ members: [camille], capabilities: ["members", "files", "notifications", "ai"], ai: { reply: () => "Summary." } });
 const response = await handler(withMember(new Request("http://tool.test/chest/tasks"), camille));
 assert.equal(await chest.emit({ type: "member.erased", data: { id: camille.id, erasure: "era_k2qhx4mzc7v3b6nfp5r2t7w4ya", deadline: "2026-10-28T10:00:00Z" } }, request => handler(request)), 204);
 assert.deepEqual(chest.acknowledged, ["era_k2qhx4mzc7v3b6nfp5r2t7w4ya"]);
@@ -493,15 +680,18 @@ assert.deepEqual((await members.list()).members.map(m => m.id), [camille.id]);
 assert.ok(chest.files.has("reports/2026.pdf"));
 assert.deepEqual(chest.notifications, [{ member: camille.id, title: "New task", path: "/chest/tasks/42", key: "task:42" }]);
 assert.equal(chest.badges.get(camille.id), 1);
+assert.equal(chest.ai[0]?.path, "/ai/chat");
 await chest.close();
 ```
 
 | Function | Gives |
 |---|---|
-| `signAssertion(member, {token?, tool?, now?})` | A `Chest-Member` header value signed like the Chest's (the token and tool of the environment by default) |
-| `withMember(request, member, options?)` | The request carrying that assertion: a new Web `Request`, or the same Node request |
-| `fakeChest({members?, former?, groups?, capabilities?, receives?, files?})` | An HTTP server on `127.0.0.1` that sets `CHEST_API`, `CHEST_TOKEN`, `CHEST_TOOL` (`tool` unless set) and answers members, groups, files, badges, notifications and erasure acknowledgments with a Chest's bounds, quotas and errors; a capability left out answers 403 (`members`, `files` and `notifications` by default; `members.email` adds the addresses; `receives` is `["member.*"]` by default, `[]` refuses acknowledgments). A former member `{id, name?, erased?}` looks up as `former`, or `erased` |
+| `signAssertion(member, {token?, tool?, now?})` | A `Chest-Member` header value signed like the Chest's for that `Member` (the token and tool of the environment by default), signed as given, so a language or a zone the Chest never sends makes `member()` refuse it |
+| `withMember(request, member, options?)` | The request carrying that assertion (the options of `signAssertion`): a new Web `Request`, or the same Node request |
+| `fakeChest({members?, former?, groups?, capabilities?, receives?, files?, ai?, chest?})` | An HTTP server on `127.0.0.1` that sets `CHEST_API`, `CHEST_TOKEN`, `CHEST_TOOL` (`tool` unless set), the Chest's `CHEST_ORGANIZATION`, `CHEST_TIME_ZONE`, `CHEST_LANGUAGE` (`chest: {organization, timeZone, language}`: `"Test organization"`, `"UTC"`, `"en"` by default) and answers members, groups, files, badges, notifications, AI and erasure acknowledgments with a Chest's bounds, quotas and errors; a capability left out answers 403 (`members`, `files`, `notifications` and `ai` by default; `members.email` adds the addresses; `receives` is `["member.*"]` by default, `[]` refuses acknowledgments). A former member `{id, name?, erased?}` looks up as `former`, or `erased` |
 | `chest.emit(event, to)` | Delivers an event (`{type, data, id?, occurredAt?}`: a new id and now by default; name an id to deliver the same event twice) signed as the Chest signs it, to `to` — the tool's address (`POST <to>/chest-events`) or a function of a Web `Request` — and says the status it answered. A `member.erased` makes its erasure one the tool may acknowledge |
+| `ai: {models?, reply?, cap?, unavailable?}` | The fake Chest's AI, deterministic and without any provider. `models`: the aliases the tool declared, `{alias, model, provider?, input?, output?}` (all four by default, `fake-default`…`fake-embedding`, provider `openrouter`, 1 and 2 USD per million tokens); another alias answers `model_not_allowed`. `reply(request)`: what a chat answers, given the wire request — a string, or `{text?, toolCalls?: {name, arguments, id?}[]}` (by default the last user message, echoed); streamed, it comes word by word, each tool call's arguments in two pieces, then the finish reason and the usage. Embeddings are unit vectors from a hash of each text (8 dimensions unless `dimensions`). Tokens count one per 4 characters; once the spending reaches `cap` (euros, 5 by default; 0 refuses at once) a call answers `cap_reached`. `unavailable` (`no_connector`, `provider_key_invalid`, `provider_unavailable`) makes chat and embeddings answer it. 60 requests a minute |
+| `chest.ai` | The tool's calls to AI, `{path, body}` in order (`body` null for a `GET`) |
 | `chest.acknowledged` | The erasures the tool acknowledged, each once |
 | `chest.members`, `chest.groups`, `chest.files` | What the fake Chest holds, to change or assert on; its `members` are those who have the tool |
 | `chest.notifications`, `chest.badges` | What the tool sent: the items kept, `{member, title, body?, path, key?}` cleaned as the Chest cleans them, in the order sent (a replaced item removed, the new one last; `withdraw` removes), and each member's badge (`Map` member → count; 0 removes it) |
@@ -535,8 +725,8 @@ npm run check:package  # npm pack, install into a temp project, import every sub
 
 `client/src` holds the modules, `client/index.ts` the package root,
 `client/test` the tests. `npm run build` compiles `client/index.ts`, the
-seven published modules (`errors`, `member`, `members`, `database`, `files`,
-`notifications`, `testing`) and the one they share (`api`, the Chest's API) —
+nine published modules (`errors`, `member`, `members`, `database`, `files`,
+`notifications`, `events`, `ai`, `testing`) and the one they share (`api`, the Chest's API) —
 TypeScript strict, ES2022, NodeNext — into `dist/`: ESM `.js`, `.d.ts` and
 their maps. `member.ts` imports nothing but `node:*`, so that a tool may copy
 it alone.

package/client/index.ts

@@ -1,14 +1,16 @@
 // The package root: every published module a tool's code uses (tool contract
-// v2). Each one is also its own subpath (@argentic/chest-sdk/member,
-// /database, /files, /members, /notifications, /events, /errors), which
-// pulls in nothing else. The files, members, notifications and events APIs
-// are namespaces here, as their names (get, list, stat, move, notify,
-// verify…) are too plain to stand alone. @argentic/chest-sdk/testing is for a tool's tests only, and
+// v2). Each one is also its own subpath (@argentic/chest-sdk/member, /chest,
+// /database, /files, /members, /notifications, /events, /ai, /errors), which
+// pulls in nothing else. The files, members, notifications, events and ai
+// APIs are namespaces here, as their names (get, list, stat, move, notify,
+// verify, chat…) are too plain to stand alone. @argentic/chest-sdk/testing is for a tool's tests only, and
 // is not here.
 export * from "./src/errors.js";
 export * from "./src/member.js";
+export * from "./src/chest.js";
 export * from "./src/database.js";
 export * as files from "./src/files.js";
 export * as members from "./src/members.js";
 export * as notifications from "./src/notifications.js";
 export * as events from "./src/events.js";
+export * as ai from "./src/ai.js";