@argentic/chest-sdk 0.3.0 → 0.4.1

package/README.md

@@ -1,13 +1,16 @@
 # Chest SDK
 
-`@argentic/chest-sdk` is what a server tool (tool contract v2) embeds to talk
+`@argentic/chest-sdk` is what a server tool (tool contract 0.4) embeds to talk
 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, AI models through the Chest — and, for the
-tool's tests, a fake Chest. The SDK has no dependency: it
-only imports `node:*`.
+(its organization, time zone, language and currency, and where the tool is
+reached), 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, AI models through the
+Chest — and, for the tool's tests, a fake Chest. It also publishes the tool
+contract ([`contract/`](contract/README.md): what `chest.json` may say, what
+the Chest builds, what migrations may do, the policies it adds) and `chest
+check`, the Chest's own validator. The SDK has no dependency: it only
+imports `node:*`.
 
 ```sh
 npm install @argentic/chest-sdk
@@ -18,23 +21,24 @@ 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, events and ai APIs as the
-namespaces `files`, `members`, `notifications`, `events` and `ai` (the
-testing module is not in the root).
+all, with the files, members, notifications, events, schedules and ai APIs
+as the namespaces `files`, `members`, `notifications`, `events`, `schedules`
+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, 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/chest` | `chest`, type `Chest`: the Chest the tool runs in — `chest.organization.name`, `chest.timeZone`, `chest.language`, `chest.currency`, `chest.today()` — and where the tool is reached — `chest.tool.teamUrl`, `chest.tool.publicUrl` —, 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/schedules` | `handle`, `verify`, types `Run`, `Handlers`, `Seen`: the runs of the tool's schedules (`"schedules"` in `chest.json`) the Chest posts to its `/chest-schedules` at their times, verified, deduplicated by id |
 | `@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), 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 |
+| `@argentic/chest-sdk/testing` | `signAssertion`, `withMember`, `fakeChest`, types `AssertionOptions`, `FakeChest`, `FakeChestOptions`, `FakeGroup`, `FakeFile`, `FakeFormer`, `FakeNotification`, `FakeEvent`, `FakeRun`, `FakeAi`, `FakeAiModel`, `FakeAiReply`, `FakeAiCall`: for the tool's own tests only |
+| `@argentic/chest-sdk` | all of the above but `testing`; `files`, `members`, `notifications`, `events`, `schedules` and `ai` as namespaces |
 
 ```ts
 import { member } from "@argentic/chest-sdk/member";
@@ -49,6 +53,10 @@ import { CapabilityNotGranted } from "@argentic/chest-sdk/errors";
 // or: import { member, chest, databaseUrl, files, members, notifications, events, ai } from "@argentic/chest-sdk";
 ```
 
+`chest check`, the Chest's validator, is a separate development package,
+`@argentic/chest-check`, not published yet (see [Check a tool](#check-a-tool--chest-check)):
+this one stays a small runtime client.
+
 Types refer to `node:http` (`IncomingMessage`): a TypeScript project needs
 `@types/node`, as any Node project does. Both `moduleResolution` `bundler` and
 `nodenext` work.
@@ -73,20 +81,53 @@ export function GET(request: Request) {
 
 ## The contract, in short
 
-A v2 tool is an ordinary web server in a container without network, run by
+A 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, its notifications and AI), and the Chest posts it the
-events it receives on `/chest-events`, through the same launcher. Rights come
+events it receives on `/chest-events` and the runs of its schedules on
+`/chest-schedules`, 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:
-the SDK makes the calls easier, it is not a security boundary. The full
-contract (manifest `chest.json`, capabilities, build from source, catalogue)
-is described in the Chest repository, `docs/architecture.md`.
+the SDK makes the calls easier, it is not a security boundary. The contract
+itself — every key of `chest.json` and its bounds, what the Chest builds,
+what migrations may create, the Content-Security-Policy it adds, Next.js on
+a Chest — is [`contract/README.md`](contract/README.md), rendered from the
+Chest's own code.
+
+## Check a tool — `chest check`
+
+```sh
+# once, in a clone of chest-by-argentic/Chest-SDK (not on npm yet)
+npm ci                                   # builds check/ too
+npx chest check /path/to/the/tool        # --json for agents and CI
+# or, in the tool's repository, a local devDependency
+npm install --save-dev /path/to/Chest-SDK/check
+npx chest check
+```
+
+`@argentic/chest-check` is `check/` of this repository, not published on npm
+yet: it runs from a clone.
+
+The Chest's own validator — the code a Chest runs on every repository it
+builds, compiled to WebAssembly (1.6 MB, in its own package, `check/` of
+this repository, so that a tool's runtime dependencies stay small) — judges the repository as
+the Chest would receive it: the files Git tracks or would add, as they are
+now, committed or not. It says `OK` with the tool's name, roles, what it
+asks and its migrations, or `Refused` with the Chest's reason (`manifest`,
+`migrations`, `no_lock`, `newer_chest`…) and the rule broken; exit status 0,
+1, or 2 when it could not run (not a Git repository). It reads nothing but
+the archive it is given, and needs no network and no Chest. Details:
+[`contract/README.md`](contract/README.md#check-a-repository).
 
-## `member(request)` — server tool (contract v2)
+`chest.json` names the version of the contract the tool is written for,
+`"chest": "0.4"` — the MAJOR.MINOR of this SDK. A Chest older than that
+refuses the tool with “This tool needs a newer version of your Chest”;
+up to its own version, a key it does not know is refused, never ignored.
 
-A v2 tool is an ordinary web server; on its team host, the Chest relays
+## `member(request)` — the member of a request
+
+A 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 a `Member`, the type the `members` API
@@ -176,13 +217,20 @@ 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.currency;          // "EUR": the Chest's currency, ISO 4217
+chest.tool.teamUrl;      // "https://tasks-chest.acme.argentic.work": where members open /chest
+chest.tool.publicUrl;    // "https://status.acme.com": the public part (its custom domain), or null
 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
+(`CHEST_ORGANIZATION`, `CHEST_TIME_ZONE`, `CHEST_LANGUAGE`, `CHEST_CURRENCY`,
+`CHEST_TEAM_URL`, `CHEST_PUBLIC_URL`), and starts every tool that is awake
+again when one changes — the owner changes the first four in Settings →
+General; a custom domain served, or no longer, changes the public address —;
+a tool asleep reads them when it wakes. The tool never asks its own admin for
+the company's name, zone or currency, nor guesses its own address from a
+request. 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.
 
@@ -195,6 +243,16 @@ needed: nothing here is more than what the Chest's pages show its members.
 - `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.
+- `currency` is the ISO 4217 code of the Chest's currency (`"EUR"` until
+  the owner sets one): the amounts of a quote, a price, an expense. Format
+  them with `Intl.NumberFormat(language, { style: "currency", currency:
+  chest.currency })`.
+- `tool.teamUrl` and `tool.publicUrl` are origins, without a path: build a
+  link where no request tells the host — an email sent from a scheduled job,
+  a calendar feed — with `new URL("/chest/tasks/42", chest.tool.teamUrl)`.
+  `publicUrl` is the company's own domain once the owner connected one, else
+  the tool's public host; `null` for a tool without a public part. Store
+  paths in your data, never these origins: they change.
 - `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.
@@ -203,11 +261,12 @@ 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.
+tests, `fakeChest({chest: {organization, timeZone, language, currency,
+teamUrl, publicUrl}})` sets them.
 
 ## `members` — who has the tool
 
-A v2 tool that declares `"capabilities": ["members"]` (approved like a
+A tool that declares `"capabilities": ["members"]` (approved like a
 permission: “Sees the name, photo, role and groups of the members who have
 access to it.”) reads the members who have it, through the Chest's API
 (`CHEST_API`, as for files). `"members.email"`, a permission of its own that
@@ -224,8 +283,9 @@ const teams = await members.groups.list();                                  // [
 
 - **Who**: exactly the members who have the tool now — by a grant, a group,
   open to all, or because they run it (owner, admins, its builders);
-  recomputed at every call. A member without access answers as an identifier
-  that does not exist (`get` → `null`, `lookup` → `unknown`).
+  recomputed at every call. `list` and `get` see only them (`get` → `null`
+  for anyone else); `lookup` also names those the tool had who no longer
+  have it (below).
 - **`list({after, limit, q, role, group})`**: ordered by name (accents aside)
   then identifier; `limit` 100 by default, 500 at most; `next` is an opaque
   cursor for `after`, `null` after the last page. `q` finds the start of a
@@ -233,10 +293,14 @@ const teams = await members.groups.list();                                  // [
   —, whatever its case and accents; `role` and `group` keep the members of that
   role or group.
 - **`lookup(ids)`**: each identifier once, in the order given: `members`,
-  `former` (`{id, name, status: "former"}`: someone who left the Chest after
-  having the tool, so a record still reads “Camille Martin (former member)”;
-  `{id, name: null, status: "erased"}` once the owner had their data erased,
-  rendered “Former member”) and `unknown`. The SDK asks 200 at a time and
+  `former` — those the tool had who no longer have it: `{id, name, status:
+  "no_access"}`, a member of the Chest who lost access to the tool (“Léa
+  Dubois (no access)”: the laptops she holds, the goals that need a new
+  owner); `{id, name, status: "former"}`, someone who left the Chest, so a
+  record still reads “Camille Martin (former member)”; `{id, name: null,
+  status: "erased"}` once the owner had their data erased, rendered “Former
+  member” — and `unknown`: an identifier the tool never had (the Chest names
+  nobody the tool never had, not even a member of the Chest). The SDK asks 200 at a time and
   keeps each answer a minute in the process (5,000 at most); `forget()`
   empties it, and so does every event of the members' lifecycle
   (`events.handle`).
@@ -269,7 +333,7 @@ To search tasks by assignee name: `members.list({ q })` first, then
 
 ## `notifications` — badges and inbox items
 
-A v2 tool that declares `"capabilities": ["notifications"]` (approved like a
+A tool that declares `"capabilities": ["notifications"]` (approved like a
 permission: “Shows counters and sends notifications, inside the Chest, to the
 members who have access to it.”) tells its members what needs their
 attention, inside the Chest only — no email, no push to a phone. Two
@@ -349,13 +413,13 @@ away by itself once handled.
 
 ## `events` — the members' lifecycle
 
-A v2 tool that holds `members` and declares `"receives": ["member.*"]` in its
+A tool that holds `members` and declares `"receives": ["member.*"]` in its
 `chest.json` (approved like a permission: “Is told when the members who have
 access to it change or leave.”) is told, on its own `POST /chest-events`:
 
 | Event | `data` | When |
 |---|---|---|
-| `member.updated` | `{id, changed: ("name" \| "photo" \| "role" \| "groups" \| "email")[]}` | Something the tool sees of a member who has it changed (`email` only with `members.email`) |
+| `member.updated` | `{id, changed: ("name" \| "photo" \| "role" \| "groups" \| "email" \| "language" \| "timeZone")[]}` | Something the tool sees of a member who has it changed (`email` only with `members.email`; `language` and `timeZone`: the language the Chest speaks to them and the zone they work in — a digest's words and hour) |
 | `access.revoked` | `{id}` | The member lost access to the tool but stays in the Chest |
 | `member.removed` | `{id}` | The member left the Chest: `lookup` now reads them `former` |
 | `member.erased` | `{id, erasure, deadline}` | The owner asked for this person's data to be erased: delete or anonymise what the tool keeps of them before `deadline` (30 days), then `acknowledgeErasure(erasure)` |
@@ -420,7 +484,7 @@ export async function POST(request: Request) {
 
 ## `ai` — AI models through the Chest
 
-A v2 tool that declares the `ai` capability calls AI models through its
+A 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
@@ -529,13 +593,14 @@ before it.
 
 ## `databaseUrl()` — database of a server tool
 
-A v2 tool that declares `"capabilities": ["database"]` in its `chest.json`
+A tool that declares `"capabilities": ["database"]` in its `chest.json`
 gets a PostgreSQL database of its own (the capability is shown and approved
 like a permission, in the approval screen). The container has no network: its
 launcher listens on `127.0.0.1` and relays each connection to the Chest. The
 launcher sets `DATABASE_URL` —
 `postgres://<user>:<password>@127.0.0.1:<port>/<database>?sslmode=disable`,
-the user and the database both named `t_<tool>` — and `PGHOST`, `PGPORT`,
+the user and the database both named `t_<tool>`, or `pb_<project>` in the
+preview of a draft Perseus Code builds — and `PGHOST`, `PGPORT`,
 `PGUSER`, `PGPASSWORD`, `PGDATABASE`, which take precedence over a variable of
 the tool with the same name. `databaseUrl()` returns `DATABASE_URL` when it has
 exactly this shape, and throws `CapabilityNotGranted` otherwise (a version
@@ -565,7 +630,7 @@ previous version working — going back to the previous version undoes nothing.
 
 ## `files` — files of a server tool
 
-A v2 tool that declares `"capabilities": ["files"]` (approved like a permission)
+A tool that declares `"capabilities": ["files"]` (approved like a permission)
 keeps private files **through its Chest**, never on its disk (the container's
 root is read-only). The launcher gives the tool
 `CHEST_API=http://127.0.0.1:<port>` — its own port, relayed to the Chest; the
@@ -576,7 +641,7 @@ its own files only.
 import * as files from "@argentic/chest-sdk/files";
 await files.put("photos/cat.png", bytes, "image/png");       // Uint8Array or text
 const file = await files.get("photos/cat.png");              // {data, type, size} or null
-const info = await files.stat("photos/cat.png");             // {name, type, size, updated, width?, height?} or null
+const info = await files.stat("photos/cat.png");             // {name, type, size, sha256, updated, width?, height?} or null
 const { files: page, next } = await files.list({ prefix: "photos/" }); // 1000 per page
 await files.move("photos/cat.png", "archive/cat.png");       // atomic; replaces archive/cat.png
 await files.delete("archive/cat.png");                       // true, or false if it did not exist
@@ -657,6 +722,18 @@ otherwise); thumbnails are made once, not counted in the quota. `stat` gives
 `width` and `height` for these images. Give a link to a member's browser,
 never to a public page.
 
+Every file the Chest answers (`put`, `stat`, `list`, `move`) carries
+`sha256`, the digest of its content in hex, as the Chest took it: compare
+it, or detect a duplicate receipt, without reading the file again.
+
+The SDK takes a link or an upload address from the Chest only in `https`
+on the team host, or on the origin of the Chest's API itself (`CHEST_API`,
+`http://127.0.0.1:<port>`): the address the tool already sends every call
+to, where only a fake Chest (`@argentic/chest-sdk/testing`) serves its
+links. A real Chest never answers one there, and no other local address is
+ever taken — so a tool a test starts in its own process (`next start` with
+the fake's environment) takes the fake's links as the test itself does.
+
 Errors: `CapabilityNotGranted` (a version without the capability, or no
 `CHEST_API`), `TooLarge` (413), `QuotaExceeded` (429), `Unavailable` (the
 Chest not reached, or an answer that is not its own: a write may or may not
@@ -664,6 +741,79 @@ have happened), `ChestError` for the rest (`invalid_type`, `no_thumbnail`,
 `not_found` for `url` and `move`…). Removing the tool removes its files; a new
 version keeps them.
 
+## `schedules` — work the tool does by itself
+
+Nothing runs in a tool's container between requests — the Chest puts a tool
+nobody uses to sleep —: a morning digest, reminders, a purge or a badge kept
+true overnight come from the Chest, which calls the tool at set times. The
+tool declares each schedule in its `chest.json`, a name and a cron line read
+on the wall clock of the Chest's time zone (`chest.timeZone`), approved in
+words (“Runs by itself: morning, weekdays at 7:30 AM”):
+
+```jsonc
+// chest.json
+{ "schedules": [{ "name": "morning", "cron": "30 7 * * 1-5" }, { "name": "retry-mail", "cron": "*/15 * * * *" }] }
+```
+
+```ts
+// app/chest-schedules/route.ts — at the root, outside /chest: the Chest calls
+// it through the tool's launcher, never from a browser (its front answers 404 there).
+import * as schedules from "@argentic/chest-sdk/schedules";
+import { chest } from "@argentic/chest-sdk/chest";
+
+export async function POST(request: Request) {
+  return new Response(null, { status: await schedules.handle(request, {
+    morning: async () => { await sendDigest(chest.today()); },
+    "retry-mail": () => retryOutbox(),
+  }, { seen }) });
+}
+```
+
+- **The line**: five fields — minute, hour, day of the month, month, day of
+  the week —, each numbers, `*`, ranges (`1-5`), lists (`1,15`) and steps
+  (`*/15`); Sunday is 0 or 7; no names nor `@daily`, one space between
+  fields. When both days are restricted, either one runs (as cron). A time
+  a change of clock skips runs once, shifted; a repeated one runs once.
+- **Bounds** (the Chest's, checked when the manifest is read): 8 schedules,
+  names of 1 to 32 lowercase letters, digits and hyphens, each running 15
+  minutes apart at least; 5 minutes a run.
+- **Approval**: running by itself is a permission, one sentence per
+  schedule. A later version that changes, adds or removes schedules of a
+  tool that already had one asks nothing more.
+- **Delivery**: `POST /chest-schedules`, the tool woken first when it
+  sleeps, body `{id: "run_…", name, scheduledAt, attempt}` signed for this
+  tool (`Chest-Schedule` header, HS256 under a key derived from
+  `CHEST_TOKEN` with the label `Chest-Schedule v1` — the scheme of events,
+  under a key of its own —, naming the run and the SHA-256 of the body, 60
+  seconds). `scheduledAt` is the time the run stands for (UTC); a run asked
+  now stands for the time it was asked.
+- **Answer once the work is done**, within 5 minutes: a 2xx is done; a 404
+  (a schedule without a handler) is given up at once; anything else, or no
+  answer, is delivered again, the same run with the same id, after 1, 5 and
+  15 minutes (`attempt` 2 to 4), unless the next time of its schedule comes
+  first. Runs of one schedule never overlap: a time that comes while the
+  previous run still runs is skipped. A server that was stopped runs a
+  missed time once when it starts again — the latest, never a backlog.
+  Longer work: do a batch per run and keep your place in the database.
+- **`handle(request, handlers, {seen?})`** answers the status to give the
+  Chest: 401 for what is not a run of the Chest for this tool, 404 for a
+  schedule without a handler, 204 for a run handled or one already in
+  `seen`. It reads the body (1 KiB at most): mount it before any body
+  parser. A handler that throws leaves the run unseen and `handle` throws:
+  answer 500, it comes again. `seen` is as for `events` (`events.memorySeen`
+  by default; a table of the tool's for runs that must never be done twice —
+  the same table serves both, the ids never meet). Make handlers idempotent
+  anyway.
+- **`verify(request)`** is the run of a delivery, or `null`; for a tool that
+  routes runs itself.
+- **The Chest's times, the members' zones**: a line is the company's clock.
+  To reach each member at *their* 8:00, run hourly (`0 * * * *`) and pick
+  the members whose local hour it is (`members.list`, `member.timeZone`).
+- **Whoever runs the tool** sees each schedule on its overview — when it
+  runs next, its last runs and why one failed — and may **Run now**; an
+  agent reads `GET /api/v1/tools/<tool>/schedules` and runs one with
+  `POST /api/v1/tools/<tool>/schedules/run {name}` (a token that writes).
+
 ## `testing` — a tool's own tests
 
 `@argentic/chest-sdk/testing` is for tests, never imported by production code.
@@ -681,6 +831,7 @@ 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");
+assert.equal(await chest.run("morning", request => handler(request)), 204);
 await chest.close();
 ```
 
@@ -688,9 +839,11 @@ await chest.close();
 |---|---|
 | `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` |
+| `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_CURRENCY`, `CHEST_TEAM_URL`, `CHEST_PUBLIC_URL` (`chest: {organization, timeZone, language, currency, teamUrl, publicUrl}`: `"Test organization"`, `"UTC"`, `"en"`, `"EUR"`, `https://<tool>-chest.chest.test`, `https://<tool>.chest.test` by default; `publicUrl: null` for a tool without a public part) 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). `former: [{id, name?, status?}]` are those the tool had who no longer have it: `lookup` answers them `no_access`, `former` (by default) or `erased` |
+| Links and uploads | The fake serves the team host's part of the files on its own origin (`chest.api`): a link from `files.url` opens the content it was signed for (the image itself for a thumbnail — a fake does not reduce it; `no_thumbnail` for a file that is not a JPEG, PNG, GIF or WebP image), until it expires or the file changes; an address from `files.uploadUrl` takes one `PUT`, within its life, of the types and size it names and whose first bytes are those of its type (403 `invalid_token`, 415 `type_refused`, 400 `type_mismatch`, 413 `too_large`, as the Chest's), named by the Chest in a folder (20 hex characters and the type's ending), and answers `201 {name, type, size}`. It checks no session: a test's `fetch` is the member's browser |
 | `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.run(name, to, {id?, scheduledAt?, attempt?})` | Delivers a run of the schedule `name` (a new id, now and attempt 1 by default; name an id to deliver the same run twice) signed as the Chest signs it, to `to` — the tool's address (`POST <to>/chest-schedules`) or a function of a Web `Request` — and says the status it answered |
 | `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 |
@@ -700,7 +853,9 @@ await chest.close();
 ## Version
 
 The package version is `version` in `package.json` (semver), published by a
-tag `vX.Y.Z` (see `PUBLISHING.md`).
+tag `vX.Y.Z` (see `PUBLISHING.md`). Its MAJOR.MINOR is the version of the
+tool contract it is written for (`"chest"` in `chest.json`): 0.4.x for the
+contract 0.4. A new contract version is a new MINOR of the SDK.
 
 ## The MCP server
 
@@ -718,11 +873,22 @@ that carry a manifest — never offers it.
 
 ```sh
 npm ci
-npm test               # build dist/, compile the tests into build/, run them
-npm run check:package  # npm pack, install into a temp project, import every subpath
-                       # from Node and through esbuild, type-check a TS consumer
+npm test               # build dist/, compile the tests into build/, check that
+                       # contract/README.md says what contract.json says, run them,
+                       # then check/'s (the chest command)
+npm run check:package  # npm pack both packages, the SDK under 200 KiB, install into a
+                       # temp project, run chest check, import every subpath from Node
+                       # and through esbuild, type-check a TS consumer
 ```
 
+`contract/contract.json`, `check/check.wasm.gz` and
+`check/check.wasm.sha256` are written by the Chest's repository
+(`scripts/build-contract.mjs`) from the code that decides; never edit them
+here. `npm run contract` renders the parts of `contract/README.md` they say;
+the words around them are written here. `check/` is the workspace of
+`@argentic/chest-check`, released with the SDK under the same version
+(`PUBLISHING.md`); `check/src/cli.ts` is the `chest` command.
+
 `client/src` holds the modules, `client/index.ts` the package root,
 `client/test` the tests. `npm run build` compiles `client/index.ts`, the
 nine published modules (`errors`, `member`, `members`, `database`, `files`,

package/client/index.ts

@@ -1,7 +1,7 @@
 // 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, /chest,
-// /database, /files, /members, /notifications, /events, /ai, /errors), which
-// pulls in nothing else. The files, members, notifications, events and ai
+// 0.4). Each one is also its own subpath (@argentic/chest-sdk/member, /chest,
+// /database, /files, /members, /notifications, /events, /schedules, /ai, /errors), which
+// pulls in nothing else. The files, members, notifications, events, schedules 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.
@@ -13,4 +13,5 @@ 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 schedules from "./src/schedules.js";
 export * as ai from "./src/ai.js";

package/client/src/api.ts

@@ -9,6 +9,18 @@ import { CapabilityNotGranted, ChestError, QuotaExceeded, RateLimited, TooLarge,
 const maxAnswer = 4 << 20;
 const deadline = 120000;
 
+// chestLink reads a link to the team host the Chest answered, at path (its
+// links, its uploads): the token it carries, or undefined for an address
+// that is not one — https, or the origin of the Chest's API itself
+// (CHEST_API), where only a fake Chest of a tool's tests serves its links:
+// the address the tool already trusts for every call, never another.
+export function chestLink(url: unknown, path: string): string | undefined {
+  if (typeof url !== "string") return undefined;
+  const found = /^(https:\/\/[A-Za-z0-9.-]{1,253}(?::[0-9]{1,5})?|http:\/\/127\.0\.0\.1:[0-9]{1,5})(\/_chest\/[a-z/]+\/)([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/u.exec(url);
+  if (!found || found[2] !== path || (found[1]!.startsWith("http:") && found[1] !== process.env["CHEST_API"])) return undefined;
+  return found[3];
+}
+
 // base is the Chest's API as the launcher gives it; without, the version holds
 // none of the capabilities that use it.
 function base(capability: string): string {

package/client/src/chest.ts

@@ -2,11 +2,13 @@ import { ChestError } from "./errors.js";
 import { languagePattern, timeZonePattern } from "./member.js";
 
 // The Chest the tool runs in, the same for every member and every request:
-// the organization it is of, its time zone and its language. The Chest sets
-// them in the tool's environment at each start (CHEST_ORGANIZATION,
-// CHEST_TIME_ZONE, CHEST_LANGUAGE) and starts the tool again when its owner
-// changes one, so they are there outside any request too: in a scheduled
-// job, at start-up, in a migration script. The Chest also sets its time zone
+// the organization it is of, its time zone, its language and its currency —
+// and where this tool is reached. The Chest sets them in the tool's
+// environment at each start (CHEST_ORGANIZATION, CHEST_TIME_ZONE,
+// CHEST_LANGUAGE, CHEST_CURRENCY, CHEST_TEAM_URL, CHEST_PUBLIC_URL) and
+// starts the tool again, when it is awake, as soon as one changes, so they
+// are there outside any request too: in a scheduled job, at start-up, in a
+// migration script. The Chest also sets its time zone
 // as the zone of the tool's database sessions: there, current_date and
 // now()::date are the Chest's day too.
 //
@@ -18,6 +20,14 @@ import { languagePattern, timeZonePattern } from "./member.js";
 // - language is the Chest's own language, a primary tag ("en", "fr"): the
 //   language of what the tool writes for no one in particular (a public page
 //   before the visitor chooses, an export). A member's is member.language.
+// - currency is the ISO 4217 code of the Chest's currency ("EUR" until the
+//   owner sets one): the amounts the tool writes — a quote, a price.
+// - tool.teamUrl is the origin of the tool's team host, where its members
+//   open /chest; tool.publicUrl the origin of its public part — the
+//   company's own domain when the owner connected one —, null for a tool
+//   without a public part. Origins, without a path: a link in an email is
+//   new URL("/chest/tasks/42", chest.tool.teamUrl). Store paths, never
+//   these origins: they change with a custom domain.
 // - today() is the date ("YYYY-MM-DD") in the Chest's zone, now or at the
 //   instant given.
 //
@@ -28,13 +38,19 @@ export type Chest = {
   readonly organization: { readonly name: string };
   readonly timeZone: string;
   readonly language: string;
+  readonly currency: string;
+  readonly tool: { readonly teamUrl: string; readonly publicUrl: string | null };
   today(at?: Date | number): string;
 };
 
 // The shapes the Chest gives: the organization's (2 to 80 characters,
 // counted as code points, without control characters), a zone's
-// (timeZonePattern, and one this runtime knows), a language's.
+// (timeZonePattern, and one this runtime knows), a language's, a currency's,
+// an origin's.
 const organizationPattern = /^[^\u0000-\u001f\u007f-\u009f]{2,80}$/u;
+// An ISO 4217 code; an https origin without a path, as the Chest gives them.
+const currencyPattern = /^[A-Z]{3}$/u;
+const originPattern = /^https:\/\/[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?(:[0-9]{1,5})?$/u;
 
 function read(name: string, valid: (value: string) => boolean): string {
   const value = process.env[name];
@@ -72,6 +88,14 @@ export const chest: Chest = {
   get language() {
     return read("CHEST_LANGUAGE", value => languagePattern.test(value));
   },
+  get currency() {
+    return read("CHEST_CURRENCY", value => currencyPattern.test(value));
+  },
+  get tool() {
+    const teamUrl = read("CHEST_TEAM_URL", value => originPattern.test(value));
+    const publicUrl = process.env["CHEST_PUBLIC_URL"] === undefined ? null : read("CHEST_PUBLIC_URL", value => originPattern.test(value));
+    return { teamUrl, publicUrl };
+  },
   today(at: Date | number = Date.now()): string {
     const instant = typeof at === "number" ? new Date(at) : at;
     if (Number.isNaN(instant.getTime())) throw new RangeError("today() needs a valid date");

package/client/src/database.ts

@@ -8,9 +8,14 @@ import { CapabilityNotGranted } from "./errors.js";
 // postgres (porsager) or pg; the SDK carries none. PGHOST, PGPORT, PGUSER,
 // PGPASSWORD and PGDATABASE say the same for a client that reads them.
 //
+// Its user is the tool's role (t_<tool>), or, in the preview of a draft
+// Perseus Code builds, the draft's (pb_<project>: its own empty database).
+//
 // Throws CapabilityNotGranted when the Chest gave no database: the version
 // does not declare it, or a DATABASE_URL of the tool's own is not the
 // Chest's. The value is a secret: never log it, never send it to a browser.
+const role = /^(t_[a-z][a-z0-9_]{0,47}|pb_[a-z2-7]{26})$/u;
+
 export function databaseUrl(): string {
   const value = process.env["DATABASE_URL"];
   if (typeof value !== "string" || value.length > 1024) throw new CapabilityNotGranted("database");
@@ -21,7 +26,7 @@ export function databaseUrl(): string {
     throw new CapabilityNotGranted("database");
   }
   const port = Number(url.port);
-  if (url.protocol !== "postgres:" || url.hostname !== "127.0.0.1" || !Number.isInteger(port) || port < 1 || port > 65535 || !/^t_[a-z][a-z0-9_]{0,47}$/u.test(url.username) || url.pathname !== "/" + url.username || url.password === "" || url.search !== "?sslmode=disable" || url.hash !== "") {
+  if (url.protocol !== "postgres:" || url.hostname !== "127.0.0.1" || !Number.isInteger(port) || port < 1 || port > 65535 || !role.test(url.username) || url.pathname !== "/" + url.username || url.password === "" || url.search !== "?sslmode=disable" || url.hash !== "") {
     throw new CapabilityNotGranted("database");
   }
   return value;