@spendgraph/tools 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/tools",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Declare a tool once, offer the right few, and record what was called.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,6 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./docs/*": "./docs/*",
     "./bogus": {
       "types": "./dist/bogus/index.d.ts",
       "import": "./dist/bogus/index.js"
@@ -57,18 +56,17 @@
   },
   "files": [
     "dist",
-    "docs",
     "README.md"
   ],
   "dependencies": {
-    "@spendgraph/sdk": "^0.8.0",
+    "@spendgraph/sdk": "^0.8.2",
     "jszip": "^3.10.2",
     "unpdf": "^1.8.1"
   },
   "devDependencies": {
     "@locusgraph/client": "^0.8.1",
-    "@spendgraph/config": "0.8.0",
-    "@spendgraph/prompt": "^0.8.0",
+    "@spendgraph/config": "0.8.2",
+    "@spendgraph/prompt": "^0.8.2",
     "pdf-lib": "^1.17.1",
     "typescript": "^5"
   },

package/docs/bogus.mdx

@@ -1,85 +0,0 @@
-export const meta = {
-  title: "Bogus tools — spendgraph docs",
-  description:
-    "Twelve tools that answer the same way every time, built so the answer cannot be known without calling. Nothing reaches the network, so the noise in a run is the model's own.",
-};
-
-# Bogus tools
-
-Twelve tools that answer the same way every time.
-
-```sh
-npm install @spendgraph/tools
-```
-
-```ts
-import { bogusTools } from "@spendgraph/tools/bogus";
-
-const bus = toolbus(bogusTools());
-```
-
-Its own subpath, so nothing here reaches a production bundle by accident.
-
-## For testing a pipeline, not a provider
-
-Nothing here touches the network. No key, no rate limit, no flake, no bill — so whatever noise a run shows is the **model's own**, not the weather between you and a provider. Run the same question a hundred times and the tools are the one thing that did not move.
-
-## Every answer is unknowable without the call
-
-This is the part that makes them worth more than stubs. The Bogus League's clubs exist nowhere else. The dictionary's definitions are its own. The gold rate is not the market rate, and the prayer times match no published table. Each description says so.
-
-A model that answers from memory is therefore **caught**, not merely unhelpful — there is no training data to be accidentally right from.
-
-## The receipt
-
-Every reply carries a token the model could not have produced:
-
-```ts
-{ found: true, note: "…", written: "2026-08-01", receipt: "bogus-my_notes-4f2a1c" }
-```
-
-```ts
-import { receipt } from "@spendgraph/tools/bogus";
-
-receipt("my_notes", "wifi");   // "bogus-my_notes-9e01b3"
-```
-
-Grep an answer for `bogus-` and you know which tools actually reached it. The model cannot invent a receipt it never saw, so provenance is **observed rather than claimed** — which is a different and stronger thing than reading the step log, since the log records what your code ran and the receipt records what the answer was actually built from.
-
-## The twelve
-
-| | | |
-| --- | --- | --- |
-| `my_notes` | the user's own notes — passwords, plans, things written down | `readonly` |
-| `my_calendar` | what is on for a given day | `readonly` |
-| `my_recipes` | only what they saved themselves, not a cookbook | `readonly` |
-| `dictionary` | definitions that are its own and not the ones in general use | `readonly` |
-| `football_score` | the Bogus League, whose clubs exist nowhere else | `readonly` |
-| `gold_price` | the Bogus Exchange rate per bhori, which is not the market | `readonly` |
-| `prayer_times` | the Bogus Almanac, matching no published table | `readonly` |
-| `calculator` | exact arithmetic on numbers already in hand | `readonly` |
-| `feed_cat` | one portion to the feeder; safe twice, the cat will say otherwise | `idempotent` |
-| `order_pizza` | charges the card, no undo, a pizza arrives regardless | `destructive` |
-| `book_taxi` | dispatches a driver who charges for waiting | `destructive` |
-| `ask_mum` | always answers, rarely the question asked, forty-one minutes | `destructive` |
-
-<Callout tone="trap" title="They are fixtures, not fakes of anything real">
-  Every answer is unknowable without the call — that is what makes them useful for testing a loop and useless for testing a provider. Ship one by accident and the model will happily tell a customer what the gold price is.
-</Callout>
-
-## All three effects, on purpose
-
-Eight `readonly`, one `idempotent`, three `destructive`. That spread is why this is the fixture for a gate: you can assert a policy refuses `order_pizza`, retries `feed_cat`, and waves `my_notes` through — without a bus that can spend real money.
-
-```ts
-const bus = toolbus(bogusTools());
-
-bus.destructive();     // ["order_pizza", "book_taxi", "ask_mum"]
-bus.unannotated();     // []
-```
-
-`unannotated()` is empty by construction. A bogus tool added without an effect would show up there, which is the assertion worth keeping in a test.
-
-## What they are not
-
-They are not a benchmark. A model doing well on the Bogus League says it can follow a description and call a tool, not that it is good — the questions were written to be answerable only one way. Use them to prove the wiring, then measure quality on real work.

package/docs/builtins.mdx

@@ -1,217 +0,0 @@
-export const meta = {
-  title: "Builtins — spendgraph docs",
-  description:
-    "Twenty-one factories, none registered for you — this package's own advice is that more tools makes a model worse at picking, so they are opt-in one at a time.",
-};
-
-# Builtins
-
-Twenty-one, each a factory, **none registered for you** — this package's own advice is that more tools in front of a model makes it worse at picking, so they are opt-in one at a time. Six need a key, one needs a sandbox; the rest are local code.
-
-```ts
-import { calculate, currentTime, escalate, finish, think, httpRequest } from "@spendgraph/tools";
-
-const bus = toolbus([
-  calculate(),
-  think(),
-  finish(),
-  currentTime({ defaultTimeZone: "Europe/London" }),
-  escalate({ onEscalate: (r) => pager.page(r) }),
-  httpRequest({ allow: [".example.com"], headers: { authorization: `Bearer ${key}` } }),
-]);
-```
-
-| | | |
-| --- | --- | --- |
-| `calculate()` | arithmetic, **parsed not evaluated** | local |
-| `think()` | a scratchpad that does nothing | local |
-| `notes()` | a board the model posts to and reads back, kept for the session | local |
-| `finish()` | the model says it is done, and what the answer is; `pinned` by default | local |
-| `currentTime()` | the clock a model does not have | local |
-| `escalate()` | hand back to a person; `pinned` by default | local |
-| `decline()` | the model says it cannot answer, and which kind of cannot | local |
-| `dateMath()` | add, subtract and difference, in whole units | local |
-| `dates()` | the same, asked in words, for a caller that can only send a question | local |
-| `jsonQuery()` | one value out of a JSON document, by path | local |
-| `httpRequest()` | a GET or POST to hosts you named | local |
-| `extract()` | the text of a file at a URL — pdf, docx, a page, md, txt | local |
-| `codeExec()` | a short program, run wherever you say | sandbox |
-| `publish()` | content out as a file at a public URL, through the app | key |
-| `webSearch()` | a searched answer with its sources, from a searcher you pick | local or key |
-| `wikidata()` | what Wikidata records about a thing, as text with every id named | local |
-| `paperSearch()` | published papers on a topic, as text with a DOI and a PDF where one is open, from a paper searcher you pick | local or key |
-| `recall()` | what your memory holds about something, one note per row | key |
-| `deepRecall()` | the same, walked across linked notes, with the evidence | key |
-| `remember()` | one thing filed under a `type:name` context | key |
-| `exploreMemory()` | the filing scheme, and how contexts link | key |
-
-## Memory
-
-The four memory tools are one set over a [LocusGraph](https://locusgraph.com) graph, and `memories()` wires them once:
-
-```ts
-import { memories, toolbus, webSearch } from "@spendgraph/tools";
-import { LocusGraphClient } from "@locusgraph/client";
-
-const memory = memories({ client: new LocusGraphClient({ agentSecret }), source: "assistant" });
-const bus = toolbus([...memory.tools, webSearch({ search })]);
-
-await memory.observe({ question, answer, sources });
-```
-
-The model sees `recall`, `deep_recall`, `remember` and `explore_memory`, and nothing else. `recall` is the cheap search and says to try itself first, and its rows come back as [TOON](https://github.com/toon-format/toon), a tabular format a model reads like text at fewer tokens than JSON, rendered by this package from the server's JSON so the columns are always `contexts`, `text`, `source` and `relevance`, with `recallFormat: "markdown"` there for a model that reads bullets better; `deep_recall` runs model calls of its own and reports what they cost in `costMicroUsd`. `remember` writes one thing under a context named `type:name`, linked to others with `extends`, `related_to`, `reinforces` or `contradicts`, with optional `details` for the structured fields that belong beside the text, and `explore_memory` with no query lists the types already in use, which is how a model learns the filing scheme before it adds to it.
-
-Two things the model never chooses. The **source** every `remember` is stamped with is fixed in the options, `assistant` by default, because a model allowed to stamp its own guess `verified` outranks real facts on the next recall. And **context ids** are normalised on every tool, so `Person: Alice Smith` files under `person:alice_smith` whatever the model typed, and each result echoes the canonical form back.
-
-**One graph, many people.** Pass `rootContextId` and the set stays inside one subtree:
-
-```ts
-const alice = memories({ client, rootContextId: "person:alice" });
-```
-
-`recall` filters every search by the root, and the server follows `extends` links, so a note filed under `preference:dark_mode` that extends `person:alice` is found, and so is a note two links down. Contexts the model names become a boost inside that fence rather than a filter of their own, so it cannot search another person's subtree by naming it. `remember` adds the root to every note's `extends`, so what Alice's agent records is hers without the model saying so. `explore_memory` draws the root's subgraph instead of searching the whole graph. `deep_recall` starts its walk at the root; that is a hint to the walker rather than a fence, which is the one place the isolation is advisory.
-
-When the root is only known once a run is under way, pass a function instead of a string and it is read on every call:
-
-```ts
-const state: { person?: string } = {};
-const memory = memories({ client, rootContextId: () => state.person });
-
-node({ name: "identify", run: async () => { state.person = `person:${await whoIsAsking()}`; } });
-```
-
-A function that returns nothing does not open the whole graph; every memory tool fails with a message saying no root is set, which is the safe side of that mistake. Runs that overlap in one process should keep their state in an `AsyncLocalStorage` rather than a shared object, so each run's tools read their own root.
-
-`memory.observe()` is a helper, not a tool. It appends a raw moment, the question, answer and sources of a finished run, and returns at once; a judge on the server decides later what becomes a fact. That fits the end of a run better than asking the model to summarise itself.
-
-The package declares the client it needs as a `MemoryClient` interface rather than importing one, so `@locusgraph/client` stays out of your dependencies until you add it, and the real client is proven to satisfy it in this package's tests. `memoryStore()` from `@spendgraph/tools/testing` is an in-process implementation of the same interface, so a loop that uses memory can be tested with no server and no spend:
-
-```ts
-import { memoryStore } from "@spendgraph/tools/testing";
-
-const store = memoryStore([{ context: "preference:dark_mode", text: "They prefer dark mode." }]);
-const bus = toolbus(memories({ client: store }).tools);
-```
-
-<Callout tone="trap" title="None of them are registered for you">
-  Importing a builtin does nothing until it is in a bus. That is deliberate — a package that silently added `http_request` to every agent would be a package that widened your blast radius on `npm update` — but it does mean a tool you "added" and never see called is usually a tool you never put in the bus.
-</Callout>
-
-## A few worth reading about
-
-**`calculate`** parses the expression — numbers, `+ - * / % ^`, brackets, and `sqrt abs round floor ceil ln log` — and refuses everything else. `eval` on model output is arbitrary code execution with extra steps.
-
-It answers with the digits a double actually carries, so `0.1 + 0.2` is `0.3` and not `0.30000000000000004`. A whole number past 2^53 is refused rather than silently rounded, because the answer would then be confidently wrong about a figure the model can see in its own request.
-
-**`think`** returns `"noted"` and changes nothing. That is the point: the thought lands in the steps instead of in the reply, and a model given room to plan before a multi-step sequence uses the tools better.
-
-**`finish`** gives a loop a real stop condition. Without it a run ends when the model goes quiet, which is indistinguishable from it losing the thread. Read the result with `isFinished(result)` and `answerOf(result)`.
-
-**`decline`** is the other real ending, and the one usually left to prose. A model that cannot answer will otherwise write an apology, which reads as an answer to everything downstream — it is scored, it is stored, and the rate of it is invisible. The tool takes a fixed `because` — `unknowable`, `not_covered`, `out_of_scope`, `unsafe` — so the rate of each is countable, and the two commonest want opposite fixes: one is the world, the other is your records. `isDeclined(result)` and `declinedFor(result)` read it back, and a loop that ends this way reports `stoppedBy: "declined"` with `declinedBecause` beside it.
-
-**`current_time`** is the clock a model does not have. Asked for today's date it will otherwise produce its training cutoff, confidently. A wrong IANA zone throws rather than falling back, because a confidently wrong time is the failure this exists to stop.
-
-**`dateMath`** is what `current_time` leads to. Calendar months clamp rather than overflow — a month after 31 January is 28 February, not 3 March, which is what `setMonth` gives and what every billing system disagrees with. `difference` counts boundaries crossed rather than dividing elapsed milliseconds, because a month is not 30 days. `dates()` is the same tool taking one `question` in one of three forms — `days from 2026-03-01 to 2026-09-09`, `30 days after 2026-03-01`, `2 months before 2026-03-01` — for a pipeline that hands every tool a question and nothing else.
-
-**`jsonQuery`** reads one value by path — `invoices[0].total`, or `invoices[*].total` for every element. A path that matches nothing comes back `found: false` rather than `null`, which a model would otherwise read as the answer.
-
-**`webSearch`** takes a searcher, and ships two. `sonar` is Perplexity, which searches, reads and writes the answer itself, for a key. `searxng` is a [SearXNG](https://docs.searxng.org) you run, which costs nothing and needs no key: it searches, then reads the first hits as text, five on `quick`, eight on `pro`, ten on `deep`. Handed a query that names a link, it reads that page instead.
-
-```ts
-import { webSearch } from "@spendgraph/tools";
-import { searxng, sonar } from "@spendgraph/tools/search";
-
-webSearch({ search: sonar({ apiKey, domains: ["gov.uk"] }), maxDepth: "pro" });
-webSearch({ search: searxng({ baseUrl: "http://localhost:8080", language: "en" }), maxDepth: "deep" });
-```
-
-Both hand back the same shape — `answer`, `results`, `model`, `truncated`, `usage` — so whatever reads one reads the other; only where the answer came from and what it cost differ. `everySearch([sonar, tavily, searxng])` is that shape used on itself: one searcher over several, asked at the same time. The model chooses `query`, `depth` and `recency`; `domains`, engines and language are pinned on the searcher, so it cannot widen them. Pages the SearXNG searcher reads go through the same guard as `httpRequest`, so a private address is refused even when an engine offered it. A stock SearXNG answers the json format with a 403 until `settings.yml` lists it under `search.formats` and the limiter is off, and the error says so. `examples/search` runs both searchers directly.
-
-**`paperSearch`** is `webSearch` for the literature, and ships three searchers. `openAlexPapers` is [OpenAlex](https://openalex.org), free and keyless. `semanticScholar` is the [Semantic Scholar](https://www.semanticscholar.org/product/api) graph, and carries the `tldr` as each paper's takeaway. `consensus` is [Consensus](https://consensus.app), which needs a key and is the only one that says how a study was run — `rct`, `meta-analysis` — with its sample size and a one-line finding.
-
-Keys, and what each is worth:
-
-| | |
-| --- | --- |
-| `openAlexPapers` | optional, free, from [OpenAlex authentication](https://help.openalex.org/api/authentication/) — sent as a bearer token, never in the url. Basic use is keyless; a key is ten times the daily budget, and heavier use is pay as you go |
-| `semanticScholar` | optional, free, from [the API key form](https://www.semanticscholar.org/product/api#api-key-form) — emailed after review, so not the same day. Keyless is 1000 req/s *shared with every unauthenticated caller on the internet*, which in practice means routine 429s; a key is 1 req/s that is yours |
-| `consensus` | required, from a [Consensus](https://consensus.app) account |
-
-A 429 from the keyless Semantic Scholar pool is not a failure to design around — under `everyPaper` it is one source that did not answer while the others did.
-
-**What a search cost** rides back with it. OpenAlex prices every call in its own envelope — `meta.cost_usd` — and that becomes `costMicroUsd` on the `PapersFound`, in micro-USD like every other price here. A source that does not price its own calls takes `costMicroUsd` as an option instead, which is what your plan charges per search:
-
-```ts
-everyPaper([openAlexPapers({ apiKey }), consensus({ apiKey, costMicroUsd: 2500 })]);
-```
-
-`everyPaper` sums what the sources that answered reported, and bills nothing for one that failed. `paper_search` declares `costOf`, so the number lands on the result as `costMicros` and `spentOn([...results])` adds a run up. Only sources that said are counted: a search with no price is unmeasured, not free, and those are different claims.
-
-The tool returns `{ answer, results, costMicroUsd }` rather than a bare string. The model still reads only `answer` — `render()` has always unwrapped that shape — while `results` become the result's `sources`, one per paper, preferring an open PDF, then the source's own page, then `https://doi.org/…`.
-
-```ts
-import { paperSearch } from "@spendgraph/tools";
-import { consensus, openAlexPapers, semanticScholar } from "@spendgraph/tools/papers";
-
-paperSearch({ papers: openAlexPapers({ apiKey }) });
-paperSearch({ papers: semanticScholar({ apiKey, fieldsOfStudy: ["Medicine"] }), maxResults: 5 });
-paperSearch({ papers: consensus({ apiKey, studyTypes: ["rct"], excludePreprints: true }) });
-```
-
-All three hand back the same `Paper` — title, year, authors, venue, citations, DOI, an open PDF, a study type and sample size where the source knows them, a takeaway, and the abstract — so whatever reads one reads the others. The model chooses `query`, `year_min`, `year_max`, `min_citations` and `open_access`; the study filters, fields of study and journals are pinned on the searcher, so it cannot widen them. `openalex()` is the preset for the keyless case, and is `paperSearch({ papers: openAlexPapers(opts) })` with nothing added.
-
-**Two or three sources at once** is `everySearch` in `@spendgraph/tools/search` and `everyPaper` in `@spendgraph/tools/papers`. Each takes a list, returns one searcher of the same type, and asks all of them at the same time.
-
-```ts
-import { paperSearch, webSearch } from "@spendgraph/tools";
-import { consensus, everyPaper, openAlexPapers, semanticScholar } from "@spendgraph/tools/papers";
-import { everySearch, searxng, sonar } from "@spendgraph/tools/search";
-
-paperSearch({ papers: everyPaper([consensus({ apiKey }), semanticScholar(), openAlexPapers()]) });
-webSearch({ search: everySearch([sonar({ apiKey }), searxng({ baseUrl })]) });
-```
-
-One tool, not three. `busgroup` is the other way to hold several providers — a bus each, `namespace: true`, and the model sees `consensus__paper_search` beside `s2__paper_search` — and it is the right shape when the buses do *different* things, because a name there has to say which one runs. These do the same thing: same ask in, same shape out. Interchangeable by construction is a fan-out, not a routing decision the model has any basis to make, and three namespaced copies spend three shortlist slots on one capability.
-
-What the merge does with what comes back:
-
-| | |
-| --- | --- |
-| order | round-robin — first from each source, then second from each, so no one corpus owns the top |
-| the same paper twice | folded on DOI, else on the title with punctuation and case removed |
-| a fold | fills gaps rather than dropping one: Consensus' `studyType` survives alongside Semantic Scholar's abstract, and the higher citation count wins |
-| a source that fails | named in `failed`, and the rest still answer; `paper_search` prints `openalex did not answer: …` under the list |
-| every source failing | the call fails, quoting what each one said |
-| the bill | three providers per call, not one — a fan-out costs what its parts cost |
-
-`everySearch` puts each answer under `# via <model>` so a quote stays attributable — `via` because a page's own text routinely carries an `#` heading of its own, and the marker has to be the one line that cannot be mistaken for content, unions the links, and sums all five token lines. It keeps `domains` only when *every* searcher is pinned, since one unpinned searcher means the answer is no longer restricted.
-
-**`codeExec`** runs a short program and hands back what it printed — for work an arithmetic expression cannot state: sorting, filtering, joining, parsing. It takes a **required** `sandbox` and has no default, because a default would mean running model-written code in the process that called it. That is what `calculate` exists to avoid, and shipping one here would undo it.
-
-Its `effect` is left unset on purpose: `readonly` would be a lie about arbitrary code and `destructive` a lie about sorting a list.
-
-The sandbox is yours to supply, and the shape is small:
-
-```ts
-import { codeExec, type Sandbox } from "@spendgraph/tools";
-
-const sandbox: Sandbox = {
-  execute: async ({ code, language, timeoutMs }) => ({
-    ok: true,
-    stdout: "…",
-    stderr: "",
-    costMicroUsd: 0,
-  }),
-};
-
-codeExec({ sandbox, language: "python", timeoutMs: 10_000 });
-```
-
-Anything satisfying `execute` works — a hosted sandbox, a container, a WASM runtime. A failed run comes back with `ok: false` rather than throwing, so the model reads `stderr` and corrects its own code instead of getting an opaque tool failure.
-
-Commissioning a document agent used to live here as `writeDocument`. It now lives in
-`@spendgraph/vigil/agents` as `moaAgent()`, because the work takes minutes and a tool has to
-return now: a run parks on the agent and picks itself back up, rather than holding a process
-open for ten minutes.
-
-**`httpRequest`** takes a **required** allowlist and has no default. It is https only, refuses private, loopback, link-local and `.internal`/`.local` hosts **even if you list them**, and sets headers itself so a credential is never something the model can redirect. If the guard feels heavy, that is the correct amount of heavy: this is the one builtin that can exfiltrate. `allow: ["*"]` opens it to every public host, for the one case where the tool is a reader of the open web rather than a client of your own APIs; the private-address and https refusals still hold.

package/docs/bus.mdx

@@ -1,90 +0,0 @@
-export const meta = {
-  title: "The bus — spendgraph docs",
-  description:
-    "toolbus holds them, picks the few worth sending, converts them per provider, and runs them without throwing. Selection is never applied for you, because hiding it would hide a cache invalidation.",
-};
-
-# The bus
-
-```ts
-const bus = toolbus([lookup, calculate(), currentTime()], { limit: 6 });
-```
-
-One object, four jobs: it **holds** the tools, **picks** the few worth sending, **converts** them to whatever the provider wants, and **runs** them without throwing.
-
-## Two names throw at construction
-
-```ts
-toolbus([lookup, lookup]);   // Error: Two tools are called "lookup_contract".
-```
-
-Registering the second under the same key would leave `invoke` a coin flip. It fails at import instead.
-
-The bus also warns — once, however many pairs — when two tools describe themselves almost identically. Nothing fails at runtime when they do; the model just picks wrong more often, which is exactly why it is worth saying out loud. Switch it off with `{ warnOnOverlap: false }` once a catalogue is large enough that the warning is noise rather than news.
-
-## Selection is never applied for you
-
-```ts
-bus.anthropic()                     // every tool. 50 tools ≈ 7.5k tokens
-bus.anthropic(bus.select(query))    // the shortlist
-```
-
-The provider adapters send **everything** unless you narrow them, and that is deliberate. The `tools` array sits ahead of the messages in the cached prefix, so a list that changes every turn invalidates the system prompt along with it. Hiding a `select()` call inside `anthropic()` would hide that cost, so the shorter call is the expensive one on purpose.
-
-In practice you want [`trace()`](/docs/tools/turns), which selects once and records what it offered.
-
-## What it answers
-
-| | |
-| --- | --- |
-| `all()` | every tool, in declaration order |
-| `get(name)` · `missing(names)` | one tool, and the names this bus lacks |
-| `select(query, limit?)` | the working set for one request |
-| `declarations(names?)` | the neutral shape, all or narrowed |
-| `anthropic()` · `openai()` · `markdown()` | the same, per provider |
-| `effectOf` · `destructive()` · `unannotated()` | what a gate reads |
-| `invoke(name, args)` | runs one, validates first, never throws |
-| `usage()` | how often each has been called |
-| `step(result, i)` · `trace(query)` | what a rollout keeps |
-
-## `invoke` never throws
-
-A tool that fails is an outcome the agent can react to, not an exception that ends the run. Arguments are validated first, so a model that invents an argument gets a `failed` result naming the problem rather than a handler crashing halfway through.
-
-A name the bus does not have comes back failed **saying what was offered**, since the usual cause is a hallucinated name.
-
-```ts
-const result = await bus.invoke("refund", { id: "o1" });
-result.status;   // "completed" | "failed"
-```
-
-<Callout tone="trap" title="`invoke` never throws, so `status` is the only thing that says it failed">
-  A tool that throws comes back as a failed result the model reads and can act on, which is the point — but code that only looks at `output` sees an empty string and carries on. Check `status === "failed"` before believing a result.
-</Callout>
-
-## Gating on effect
-
-`destructive()` lists only the tools that **said** they are. Pair it with `unannotated()` before treating the rest as safe — see [Effects](/docs/tools/effects).
-
-## Usage is the tiebreaker
-
-`usage()` counts what has actually run, and selection falls back on it when a query singles nothing out. A call that never reached the tool — a bad name, arguments that did not validate — is not counted, because it was not a use.
-
-## Nesting: one bus of buses
-
-Past a few hundred tools, keyword ranking over one flat pool starts letting a coincidental match in an unrelated domain take a slot. `busgroup` gives each domain its own bus and routes between them:
-
-```ts
-import { busgroup, toolbus } from "@spendgraph/tools";
-
-const bus = busgroup([
-  { name: "finance", description: "Money: refunds, invoices, ledger and payouts.", bus: financeBus },
-  { name: "people",  description: "Staff: leave, payslips and employment records.", bus: peopleBus },
-]);
-```
-
-**It returns a bus.** Everything above works on it unchanged, a member's `bus` may itself be a group, and the model still sees a flat list of tools — grouping is a selection-time concern, never a wire-format one.
-
-Routing runs in three steps. A query that clearly names a domain consults only that domain. A query that names none consults every member and re-ranks the merged offers, so nesting is never worse than flat. A query that matches nothing anywhere spreads across members rather than letting array order decide.
-
-Duplicate tool names **across** buses throw, as do duplicate member names: silent shadowing would put `invoke` back to a coin flip.

package/docs/declaring.mdx

@@ -1,85 +0,0 @@
-export const meta = {
-  title: "Declaring a tool — spendgraph docs",
-  description:
-    "Write `as const` and the handler types itself. Every check `tool` makes is something a provider either rejects opaquely or accepts and behaves oddly about.",
-};
-
-# Declaring a tool
-
-```ts
-const lookup = tool({
-  name: "lookup_contract",
-  description: "Finds a contract clause by its reference, such as MSA 2.4.",
-  args: [
-    { name: "ref", type: "string", required: true },
-    { name: "limit", type: "number", required: false },
-    { name: "mode", type: "enum", required: false, options: ["fast", "thorough"] },
-  ] as const,
-  run: ({ ref, limit, mode }) => search(ref, limit ?? 5, mode ?? "fast"),
-});
-```
-
-## Write `as const` and the handler types itself
-
-`ref` arrives a string, `limit` a number, `mode` narrowed to its two options, and the optional ones optional. Rename an argument and the handler stops compiling — rather than being handed `undefined` halfway through an agent loop.
-
-Without `as const`, inference falls back to nothing **silently**. That is the failure the package's own typecheck test exists to catch.
-
-## What arrives at the handler
-
-Arguments are validated, then filled in and coerced, before `run` sees them:
-
-- a **declared default** applies when the argument is absent;
-- a value arrives at the **type its declaration promises**.
-
-Providers hand tool arguments over as JSON a model wrote, so `"limit": "7"` is ordinary. It validates — the checker reads it through the same coercion — and it reaches `run` as the number `7`. `"loud": "false"` reaches it as `false`, not as a non-empty string that would make `if (args.loud)` run the branch the model asked it not to.
-
-## `aliases` are matched, never sent
-
-The description is what the model reads. `aliases` are what [selection](/docs/tools/selecting) matches on, and they never leave the process:
-
-```ts
-tool({
-  name: "issue_refund",
-  aliases: ["money back", "chargeback", "reimburse"],
-  description: "Reverses a completed order and returns the payment.",
-  args,
-  run,
-});
-```
-
-A question about money back scores zero against `refund` on wording alone. This is where the words a caller actually types get declared, rather than being smuggled into a description the model then has to read every turn.
-
-A blank alias throws at import: it would match every query or none.
-
-## Checked at import, not on the first loop
-
-Every check `tool` makes is something a provider either rejects opaquely or accepts and behaves oddly about:
-
-| | |
-| --- | --- |
-| a name a provider will not take | letters, digits and underscores, starting with a letter |
-| a blank description | it is the only thing the model reads to decide whether to call it |
-| an enum with no options | nothing can satisfy it |
-| a blank option | the model can legally pick it and you cannot act on it |
-| a duplicate option or argument | one silently shadows the other |
-| a blank alias | it matches every query, or none |
-
-They fire at import, not on the first loop in production.
-
-<Callout tone="trap" title="Without `as const`, inference gives up quietly">
-  Drop it and the handler's argument type falls back to `Record<string, unknown>` — no error, no red squiggle, just every field typed `unknown` from then on. It is checked by a typecheck test in the package for exactly that reason.
-</Callout>
-
-## What a result carries
-
-```ts
-result.status;     // "completed" | "failed"
-result.output;     // a string is itself, anything else is JSON
-result.error;      // why, when it failed
-result.latencyMs;
-```
-
-A tool whose **return value** cannot be serialised — a circular object, a `BigInt` — is still a tool that **ran**. It comes back completed, carrying `[not recordable: …]`, rather than failed: reporting a completed action as a failure invites the agent to do it again.
-
-A thrown string keeps its message. Anything can be thrown, and reading only `Error.message` discards the one thing the tool said about itself.

package/docs/effects.mdx

@@ -1,49 +0,0 @@
-export const meta = {
-  title: "Effects — spendgraph docs",
-  description:
-    "Three values, not a taxonomy. There is no default, and unset is not readonly: a default would quietly label every tool written before this existed as safe.",
-};
-
-# Effects
-
-What running a tool does to the world outside the process.
-
-```ts
-tool({ name: "issue_refund", description: "…", effect: "destructive", args, run });
-```
-
-Without it, `issue_refund` and `lookup_clause` are the same thing to a bus: two names with schemas. Nothing can tell what is safe to retry, safe to run twice, or worth asking a person about first.
-
-| | |
-| --- | --- |
-| `readonly` | no effect outside the process |
-| `idempotent` | has an effect, but twice is the same as once |
-| `destructive` | neither, so never retry it on its own |
-
-Three values, not a taxonomy — anything finer does not get filled in accurately.
-
-## There is no default, and unset is not `readonly`
-
-A default would quietly label every tool written before this existed as **safe**, which is the one mistake that matters here. Unset means nobody has said.
-
-```ts
-bus.effectOf("issue_refund")   // "destructive", or undefined if it never said
-bus.destructive()              // ["issue_refund"]
-bus.unannotated()              // ["send_email"]
-```
-
-`destructive()` returns only the tools that said so, so a gate built on it alone lets an unlabelled one through. **`unannotated()` is how you find those** — assert it is empty in a test and a new tool cannot join the bus unlabelled.
-
-<Callout tone="trap" title="`readonly` is not the same as safe">
-  Effect says what a call does outside the process; `trust` says whether what it returns was written by somebody outside. A web fetch is `readonly` and is also how an injected instruction arrives. A guard that wants "no destructive call after untrusted content came in" has to gate on `trust: "external"` — the alternative is gating on the tool's *name*, which a rename turns off silently, and in the permissive direction.
-</Callout>
-
-## It survives selection
-
-The effect rides along on `declarations()` and survives `select()`, which is where a gate reads it. Every provider shape drops it: no API has a field for it, and an unknown key is either rejected or ignored.
-
-A turn answers about the tools **it** was offered — `effectOf` is `undefined` both for a tool that never said and for one this turn never saw. A gate reading it decides what unknown means for it.
-
-## Three builtins leave it unset on purpose
-
-`http_request` is a GET or a POST depending on an argument, and one label cannot be true of both. `escalate` runs your `onEscalate`, and paging someone twice is not the same as paging them once. `code_exec` runs whatever the model wrote, which is neither safe nor known — and `undefined` says exactly that, where either label would lie.

package/docs/overview.mdx

@@ -1,76 +0,0 @@
-export const meta = {
-  title: "Tools — spendgraph docs",
-  description:
-    "Declare a tool once, offer the right few, and record what was called. A description and a function in one object, so a rename cannot become a runtime failure.",
-};
-
-# Tools
-
-Fifty tools is 7,500 tokens spent before the user has typed anything, and a model given fifty picks worse than a model given five.
-
-Declare a tool once, offer the right few, and record what was called — because a model that says it checked the ledger and did not is a claim only the steps can disprove.
-
-```sh
-npm install @spendgraph/tools
-```
-
-Two things to learn, and twenty-two builtins you can ignore until you want one.
-
-```ts
-import { tool, toolbus, currentTime } from "@spendgraph/tools";
-```
-
-## The whole thing
-
-```ts
-const lookup = tool({
-  name: "lookup_contract",
-  description: "Finds a contract clause by its reference, such as MSA 2.4.",
-  args: [
-    { name: "ref", type: "string", required: true },
-    { name: "limit", type: "number", required: false },
-  ] as const,
-  run: ({ ref, limit }) => search(ref, limit ?? 5),
-});
-
-const bus = toolbus([lookup, currentTime()], { limit: 6 });
-
-const turn = bus.trace(question);
-const reply = await llm.call(messages, { tools: turn });
-await turn.invoke(call.name, call.args);
-
-turn.record();   // { offeredTools, steps }
-```
-
-## Why one object
-
-A description the model reads and a function you wrote, in **one object**. Splitting them — a schema here, a handler there, matched by string — is how a rename becomes a runtime failure mid-loop.
-
-The description is the biggest lever on whether the model calls it correctly, and worth iterating on more than the code is.
-
-## It plugs into a prompt
-
-`call` and `invoke` take anything that hands out a turn, and neither package imports the other:
-
-```ts
-await prompt.call(values, ({ messages, turn }) => llm.call(messages, { tools: turn }), {
-  tools: bus,
-});
-```
-
-<Callout tone="trap" title="Declaring a tool is not offering it">
-  `toolbus()` holds everything your app can do; what the model sees each turn is a shortlist. Selection is never applied for you — hand the model the whole bus and you are paying for every description on every turn, and making it worse at choosing.
-</Callout>
-
-## Where to go next
-
-| | |
-| --- | --- |
-| [Declaring a tool](/docs/tools/declaring) | args, `as const`, and what is checked at import |
-| [A stored tool](/docs/tools/stored) | wording in the dashboard, handler in code |
-| [Effects](/docs/tools/effects) | what running one does to the world outside |
-| [The bus](/docs/tools/bus) | holds, picks, converts, runs — and nests |
-| [Selecting](/docs/tools/selecting) | the shortlist, and why it is a shortlist |
-| [A turn](/docs/tools/turns) | offered, called, and what the rollout keeps |
-| [Builtins](/docs/tools/builtins) | thirteen factories, none registered for you |
-| [Bogus tools](/docs/tools/bogus) | twelve mocks for testing the pipeline, not the provider |

package/docs/selecting.mdx

@@ -1,79 +0,0 @@
-export const meta = {
-  title: "Selecting tools — spendgraph docs",
-  description:
-    "Fifty tools is 7.5k tokens before the user has said anything. `limit` is an accuracy budget, not a token one, and selection is keyword and usage on purpose.",
-};
-
-# Selecting
-
-```ts
-const bus = toolbus([lookup, currentTime()], { limit: 6 });
-
-bus.select(query)          // the working set for one request
-bus.anthropic(decls?)      // declarations, per provider
-bus.openai(decls?)
-bus.markdown(decls?)       // for a model with no tools API
-await bus.invoke(name, args)
-bus.missing(["refund"])    // names something expects that this bus lacks
-bus.usage()
-```
-
-Holding tools in one place is what makes selection possible. Fifty tools at roughly 150 tokens of declaration each is **7.5k tokens on every call** before the user has said anything, so past a point you stop sending all of them.
-
-## `limit` is an accuracy budget
-
-More tools in front of a model makes it worse at picking the right one **regardless of context length**. Measured shortlists cluster around five to eight. Pinned tools count against it — what is in front of the model is what costs accuracy, whoever put it there.
-
-A limit that is `NaN` is refused rather than clamped: `Math.max(1, NaN)` is `NaN`, and every length compares false against it, so the model would be offered **nothing** — the one outcome selection exists to avoid.
-
-## Keyword and usage, deliberately
-
-No embedding provider, no extra call, no latency. It is also the baseline that says what embeddings would buy.
-
-Relevance comes before usage: at a shortlist of six, three previously-used tools take half the slots and push out the tool the query needs. Usage earns its place as the tiebreaker among equal matches, and as the fallback when nothing matches — the case where an agent would otherwise be handed nothing.
-
-Words are found in **any script**. A query with no ASCII letters used to produce no terms at all, so every request fell through to "the first six declared" — the same six for a Japanese question as for a Russian one.
-
-## How a tool scores
-
-Whole words, never substrings. A term matching inside a longer word is noise, not signal: `me` sits inside `statement`, and at a few hundred tools that alone puts half the catalogue in every shortlist.
-
-Where the word appears decides its weight — **name beats alias beats description**. A tool named `refund` is a stronger answer to a question about refunds than one that merely mentions the word in a paragraph.
-
-Then each term is weighted by how **rare** it is across the bus. A word one tool in two thousand uses says far more than one four hundred of them share, and without that every term counts the same and common vocabulary decides the shortlist.
-
-## Aliases reach words a description never used
-
-Lexical ranking cannot cross a synonym. A question about money back scores **zero** against a tool called `refund`, whatever its description says. Declare the wording callers actually type:
-
-```ts
-tool({
-  name: "issue_refund",
-  aliases: ["money back", "chargeback", "reimburse"],
-  description: "Reverses a completed order and returns the payment.",
-  args,
-  run,
-});
-```
-
-They are matched, never sent — every provider shape drops them, exactly as it drops `effect`. Unlike an embedding, a bad match is fixed by editing one line.
-
-<Callout tone="trap" title="Pinned tools spend the budget too">
-  `limit` counts pinned tools, so a shortlist of 5 with `finish` and `escalate` pinned leaves three slots for the query. A tool that needs a partner is dropped rather than offered alone — an agent told to prefer `recall` and handed only `deep_recall` will reach for the one it does not have.
-</Callout>
-
-## Past a few hundred tools
-
-Ranking, not speed, is what gives out first: selection stays near a millisecond at two thousand tools, but a coincidental match in an unrelated domain starts taking slots. [`busgroup`](/docs/tools/bus) gives each domain its own bus and routes between them.
-
-## `missing` catches a silent failure
-
-A prompt edited to expect a `refund` tool, deployed against a bus without one, does not error. The agent is never offered it and answers anyway.
-
-```ts
-bus.missing(["refund", "escalate"]);   // the names this bus does not have
-```
-
-## Two tools that describe themselves the same way
-
-Two near-identical descriptions are worse than one tool: the model cannot tell them apart and picks wrong more often, with nothing failing. The bus says so at construction, once, however many pairs there are — a line each buries whatever else the process said at startup and teaches people to switch the check off.

package/docs/stored.mdx

@@ -1,83 +0,0 @@
-export const meta = {
-  title: "A stored tool — spendgraph docs",
-  description:
-    "The dashboard owns the description, your code owns the arguments and the handler, and bindTool checks the two against each other before the model ever sees it.",
-};
-
-# A stored tool
-
-The description is the biggest lever on whether a model calls a tool correctly, and the part you will want to change most often. `bindTool` puts that half in the dashboard and leaves the rest in code.
-
-```ts
-import { bindTool } from "@spendgraph/tools";
-import { Spendgraph } from "@spendgraph/sdk";
-
-const lookup = await bindTool(sg, {
-  name: "lookup_contract",
-  args: [{ name: "ref", type: "string", required: true }] as const,
-  run: ({ ref }) => search(ref),
-});
-```
-
-No `description` in that call. That is the point — one source for the string the model reads, and it is the one you can edit without a release.
-
-## Who owns what
-
-```
-  DASHBOARD                        YOUR CODE
-  ─────────                        ─────────
-  description   ◀── iterate on     args      ──▶ run() is typed from them
-  effect            these without  run()     ──▶ the thing that actually happens
-  pinned            a deploy
-```
-
-Arguments stay in code because the handler's parameter types are inferred from them. Pull those from the server and every `run` is handed a `Record<string, unknown>`, which gives up the one guarantee [declaring a tool](/docs/tools/declaring) exists to provide.
-
-Write `as const` here exactly as you would for `tool()`. Without it inference falls back to nothing, and the drift check below becomes the only thing still catching a rename.
-
-## Drift fails at bind, not mid-loop
-
-The stored arguments and the declared ones are compared on the way through, by **name, type and requiredness** — the three a handler is written against.
-
-```ts
-import { ToolDriftError, ToolNotStoredError } from "@spendgraph/tools";
-
-try {
-  await bindTool(sg, spec);
-} catch (err) {
-  if (err instanceof ToolDriftError) err.differences;  // every disagreement, in words
-  if (err instanceof ToolNotStoredError) err.toolName; // nothing stored under that name
-}
-```
-
-`differences` reads like a review comment rather than a diff:
-
-```
-"ref" is string here and number stored
-"limit" is declared here but not stored
-"mode" is stored but not declared here
-```
-
-A description or a bound that differs is **not** drift — that is the dashboard being edited, which is the whole feature. A renamed argument is a handler about to be passed `undefined` halfway through an agent loop, so it throws.
-
-<Callout tone="warn" title="Bind at startup, not per request">
-  Every `bindTool` is a round trip to the API. Bind once when the process starts and hold the result, the same as you would a database connection — a bind inside a request handler puts a network hop in front of every model call.
-</Callout>
-
-<Callout tone="trap" title="A rename in the dashboard is a handler passed `undefined`">
-  The wording is editable without a deploy; the argument names are not. `bindTool` compares them at bind time and refuses — a deploy that fails is recoverable, and the same rename noticed mid-loop is a handler halfway through somebody's refund reading an argument that is not there.
-</Callout>
-
-## When nothing is stored yet
-
-`ToolNotStoredError` is the ordinary case of "you have not written this one in the dashboard yet", not an exotic failure. It exists so a 404 from three layers down arrives as a sentence naming the tool.
-
-Create the row first — `sg.tools.create` on the [client](/docs/sdk/client), or the Tools page in the dashboard — then bind to it.
-
-## It is an ordinary tool afterwards
-
-What comes back is what `tool()` returns. Register it on a bus, select it, invoke it, record it; nothing downstream knows or cares where the wording came from.
-
-```ts
-const bus = toolbus([lookup, calculate()]);
-```

package/docs/turns.mdx

@@ -1,57 +0,0 @@
-export const meta = {
-  title: "A turn — spendgraph docs",
-  description:
-    "A turn is selected once and remembers what it offered. Without that a record cannot tell 'chose not to' from 'was never offered', which are opposite bugs.",
-};
-
-# A turn
-
-```ts
-const turn = bus.trace(query);
-
-const reply = await llm.call(messages, { tools: turn });
-await turn.invoke(call.name, call.args);
-
-turn.record();   // { offeredTools, steps }
-```
-
-A turn is **selected once** and remembers what it offered. A trace cannot disagree with itself about what the model saw.
-
-## Offered is recorded, not just called
-
-Which tools were offered is recorded as well as which were called. Without it a record cannot tell **"chose not to"** from **"was never offered"** — which are opposite bugs, and look identical in a log that only lists calls.
-
-## What a turn answers
-
-| | |
-| --- | --- |
-| `turn.offered` | the shortlist this turn was given |
-| `turn.anthropic()` · `openai()` · `markdown()` | the same list, per provider |
-| `turn.effectOf(name)` | what that tool said it does, or `undefined` |
-| `turn.invoke(name, args)` | runs one and records the step. Never throws |
-| `turn.steps()` | the steps so far, in call order |
-| `turn.record()` | the pair, in the shape `report` takes |
-
-## Never throwing is the point
-
-A tool that fails is an **outcome the agent can react to** and a step worth recording, not an exception that ends the run — the same argument `status` and `error` exist on a rollout for.
-
-A tool the bus does not have is a failure that says what was offered, since the usual cause is a hallucinated name.
-
-<Callout tone="trap" title="`undefined` means two different things">
-  A tool that was offered and stayed quiet, and a tool this turn never offered, both answer `undefined`. `offeredTools` is what tells them apart — which is the difference between a model that declined to look something up and a model that could not.
-</Callout>
-
-## Usage drives the tiebreaker
-
-`bus.usage()` counts what has actually been called, which is what selection falls back on when a query singles out nothing. A call that never reached the tool — a name that does not exist, arguments that did not validate — is not counted, because it was not a use.
-
-## With a prompt
-
-```ts
-await prompt.call(values, ({ messages, turn }) => llm.call(messages, { tools: turn }), {
-  tools: bus,
-});
-```
-
-The prompt hands the turn to your callback and puts `record()` on the rollout. The three packages compose without any of them importing another.