@spendgraph/tools 0.6.0 → 0.8.0

package/dist/testing/store.js

@@ -0,0 +1,4 @@
+const O={policy:.95,verified:.9,tool:.8,document:.75,user:.7,assistant:.6,derived:.55,system:.5},g=c=>new Set(c.toLowerCase().split(/[^a-z0-9]+/).filter(o=>o.length>2));function w(c,o){const r=g(c),i=g(`${o.text} ${o.context.replace(":"," ")}`);let d=0;for(const p of r)i.has(p)&&(d+=1);return r.size===0?0:d/r.size}const z=c=>O[c]??.5,$=(c,o)=>c.map(r=>({memory:r,score:w(o,r)*.75+z(r.source)*.25})).filter(r=>w(o,r.memory)>0).sort((r,i)=>i.score-r.score),k=c=>[...c.extends,...c.related_to,...c.reinforces,...c.contradicts],h=(c,o,r,i=new Set)=>o===r?!0:i.has(o)?!1:(i.add(o),c.filter(d=>d.context===o).flatMap(k).some(d=>h(c,d,r,i))),v=(c,o,r)=>!r?.length||r.some(i=>h(c,o.context,i)||k(o).some(d=>h(c,d,i)));function T(c=[]){const o=[],r=[];let i=1;const d=t=>{const s={id:`m${i++}`,context:t.context,kind:t.kind??"fact",source:t.source??"assistant",text:t.text,details:t.details??{},extends:t.extends??[],related_to:t.related_to??[],reinforces:t.reinforces??[],contradicts:t.contradicts??[]};return o.push(s),s},p=()=>{const t=new Map;for(const s of o)t.set(s.context,(t.get(s.context)??0)+1);return[...t].map(([s,e])=>{const n=s.indexOf(":");return{context_id:s,context_type:s.slice(0,n),context_name:s.slice(n+1),reference_count:e}})},S=t=>{const s=[];for(const e of o)e.context===t?(s.push(...e.extends.map(n=>`extends \u2192 ${n}`)),s.push(...e.related_to.map(n=>`related_to \u2192 ${n}`)),s.push(...e.reinforces.map(n=>`reinforces \u2192 ${n}`)),s.push(...e.contradicts.map(n=>`contradicts \u2192 ${n}`))):(e.extends.includes(t)&&s.push(`extended_by \u2190 ${e.context}`),e.related_to.includes(t)&&s.push(`related_to \u2190 ${e.context}`),e.reinforces.includes(t)&&s.push(`reinforced_by \u2190 ${e.context}`),e.contradicts.includes(t)&&s.push(`contradicted_by \u2190 ${e.context}`));return[...new Set(s)]},b=t=>t.map((s,e)=>`  ${e===t.length-1?"\u2514\u2500":"\u251C\u2500"} ${s}`),y=t=>`${t.map(s=>[s.context_id,...b(S(s.context_id))].join(`
+`)).join(`
+`)}
+`;for(const t of c)d(t);return{memories:o,observed:r,remember:d,async retrieveMemories(t){const e=$(o.filter(n=>v(o,n,t.contextIds)),t.query).filter(({memory:n})=>!t.sources?.length||t.sources.includes(n.source)).slice(0,t.limit??10).map(({memory:n,score:l})=>({locus_id:n.id,context_ids:[n.context,...n.extends,...n.related_to,...n.reinforces].sort(),text:n.text,score:l,source:n.source,kind:n.kind}));return{items_found:e.length,items:e}},async deepRecall(t){const e=$(o.filter(n=>v(o,n,t.contextIds)),t.question).map(({memory:n,score:l})=>({text:n.text,source:n.source,locus:n.id,contexts:[n.context],score:l}));return{facts:e,contexts_walked:[...new Set(e.flatMap(n=>n.contexts))],...e[0]?{summary:e[0].text}:{},coverage:e.length?"full":"partial",fallback:!1,usage:{cost_usd:0}}},async storeEventsBatch(t){const s=t.map(e=>{const{data:n,...l}=e.payload;return d({context:e.context_id??"topic:untitled",text:typeof n=="string"?n:JSON.stringify(e.payload),details:l,kind:e.event_kind,source:e.source,extends:e.extends,related_to:e.related_to,reinforces:e.reinforces,contradicts:e.contradicts}),{status:"recorded",event_id:`m${i-1}`,relevance:"high"}});return{stored:s.length,filtered:0,failed:0,results:s}},async searchContexts(t,s,e){const n=t.toLowerCase(),l=p().filter(x=>!e?.context_type||x.context_type===e.context_type).filter(x=>x.context_id.toLowerCase().includes(n)).slice(0,e?.page_size??20);return{contexts:l,total:l.length,...e?.include==="relationships"?{relationships_text:y(l)}:{}}},async listContextTypes(){const t=new Map;for(const e of p())t.set(e.context_type,(t.get(e.context_type)??0)+e.reference_count);const s=[...t].map(([e,n])=>({context_type:e,count:n}));return{context_types:s,total:s.length}},async getContextGraph(t){const s=`${t.contextType}:${t.contextName}`,e=t.depth??1,n=p(),l=o.flatMap(a=>[...a.extends.map(f=>({from:a.context,to:f,link_type:"extends"})),...a.related_to.map(f=>({from:a.context,to:f,link_type:"related_to"})),...a.reinforces.map(f=>({from:a.context,to:f,link_type:"reinforces"})),...a.contradicts.map(f=>({from:a.context,to:f,link_type:"contradicts"}))]),x=new Set([s]);let _=[s];for(let a=0;a<e&&_.length;a+=1){const f=l.filter(u=>_.includes(u.from)||_.includes(u.to)).flatMap(u=>[u.from,u.to]).filter(u=>!x.has(u));for(const u of f)x.add(u);_=[...new Set(f)]}const M=n.filter(a=>x.has(a.context_id)),C=[...new Set(l.filter(a=>x.has(a.from)&&x.has(a.to)))];return{nodes:M,edges:C}},async observe(t){return r.push({source:t.source,payload:t.payload,...t.stream?{stream:t.stream}:{}}),{observed:!0}}}}export{T as memoryStore};

package/dist/tool/tool.d.ts

@@ -1,4 +1,4 @@
-import type { ArgSpec, ArgsOf, Effect, Tool } from "../types/index.js";
+import type { ArgSpec, ArgsOf, Effect, Tool, Trust } from "../types/index.js";
 export interface ToolSpec<T extends readonly ArgSpec[]> {
     name: string;
     description: string;
@@ -6,6 +6,13 @@ export interface ToolSpec<T extends readonly ArgSpec[]> {
     aliases?: readonly string[];
     pinned?: boolean;
     effect?: Effect;
+    trust?: Trust;
+    costOf?(value: unknown): number | undefined;
+    needs?: readonly string[];
+    wants?: {
+        name: string;
+        description: string;
+    };
     run(args: ArgsOf<T>): Promise<unknown> | unknown;
 }
 /**

package/dist/tool/tool.js

@@ -1 +1 @@
-const r=/^[A-Za-z_][A-Za-z0-9_]*$/,i=["readonly","idempotent","destructive"];function a(n,e){if(!e.options?.length)throw new Error(`Tool "${n}" argument "${e.name}" is an enum with no options, so nothing can satisfy it.`);const t=new Set;for(const o of e.options){if(!o.trim())throw new Error(`Tool "${n}" argument "${e.name}" has a blank option, which the model can pick and you cannot act on.`);if(t.has(o))throw new Error(`Tool "${n}" argument "${e.name}" lists "${o}" twice.`);t.add(o)}}function s(n,e){if(e){for(const t of e)if(!t.trim())throw new Error(`Tool "${n}" has a blank alias, which matches every query or none.`)}}function f(n,e){const t=new Set;for(const o of e){if(!r.test(o.name))throw new Error(`Tool "${n}" argument "${o.name}" is not a usable name.`);if(t.has(o.name))throw new Error(`Tool "${n}" declares "${o.name}" twice.`);t.add(o.name),o.type==="enum"&&a(n,o)}}function h(n){if(!r.test(n.name))throw new Error(`Tool name "${n.name}" must be letters, digits and underscores, starting with a letter.`);if(!n.description.trim())throw new Error(`Tool "${n.name}" has no description. It is the only thing the model reads to decide whether to call it.`);if(f(n.name,n.args),s(n.name,n.aliases),n.effect!==void 0&&!i.includes(n.effect))throw new Error(`Tool "${n.name}" declares effect "${n.effect}", which is not one of ${i.join(", ")}.`);return{name:n.name,description:n.description,args:n.args.map(e=>({...e,options:e.options?[...e.options]:void 0})),...n.aliases?.length?{aliases:[...n.aliases]}:{},pinned:n.pinned,...n.effect?{effect:n.effect}:{},run:n.run}}export{h as tool};
+const r=/^[A-Za-z_][A-Za-z0-9_]*$/,i=["readonly","idempotent","destructive"],a=["own","external"];function s(n,t){if(!t.options?.length)throw new Error(`Tool "${n}" argument "${t.name}" is an enum with no options, so nothing can satisfy it.`);const e=new Set;for(const o of t.options){if(!o.trim())throw new Error(`Tool "${n}" argument "${t.name}" has a blank option, which the model can pick and you cannot act on.`);if(e.has(o))throw new Error(`Tool "${n}" argument "${t.name}" lists "${o}" twice.`);e.add(o)}}function f(n,t){if(t){for(const e of t)if(!e.trim())throw new Error(`Tool "${n}" has a blank alias, which matches every query or none.`)}}function h(n,t){const e=new Set;for(const o of t){if(!r.test(o.name))throw new Error(`Tool "${n}" argument "${o.name}" is not a usable name.`);if(e.has(o.name))throw new Error(`Tool "${n}" declares "${o.name}" twice.`);e.add(o.name),o.type==="enum"&&s(n,o)}}function d(n){if(!r.test(n.name))throw new Error(`Tool name "${n.name}" must be letters, digits and underscores, starting with a letter.`);if(!n.description.trim())throw new Error(`Tool "${n.name}" has no description. It is the only thing the model reads to decide whether to call it.`);if(h(n.name,n.args),f(n.name,n.aliases),n.effect!==void 0&&!i.includes(n.effect))throw new Error(`Tool "${n.name}" declares effect "${n.effect}", which is not one of ${i.join(", ")}.`);if(n.trust!==void 0&&!a.includes(n.trust))throw new Error(`Tool "${n.name}" declares trust "${n.trust}", which is not one of ${a.join(", ")}.`);return{name:n.name,description:n.description,args:n.args.map(t=>({...t,options:t.options?[...t.options]:void 0})),...n.aliases?.length?{aliases:[...n.aliases]}:{},pinned:n.pinned,...n.effect?{effect:n.effect}:{},...n.trust?{trust:n.trust}:{},...n.costOf?{costOf:n.costOf}:{},...n.needs?.length?{needs:[...n.needs]}:{},...n.wants?{wants:{...n.wants}}:{},run:n.run}}export{d as tool};

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
 export type { ToolResult } from "./result.js";
-export type { ArgSpec, ArgsOf, ArgValue, Effect, Tool, ToolDeclaration } from "./tool.js";
+export type { ArgSpec, ArgsOf, ArgValue, Effect, Tool, ToolDeclaration, Trust } from "./tool.js";

package/dist/types/result.d.ts

@@ -1,3 +1,5 @@
+import type { Source } from "../search/search.js";
+import type { Trust } from "./tool.js";
 /** What happened when one was called. */
 export interface ToolResult {
     name: string;
@@ -7,4 +9,40 @@ export interface ToolResult {
     output: string;
     error?: string;
     latencyMs: number;
+    /**
+     * What the tool declared about where its content came from.
+     *
+     * Carried onto the result so a hook watching what has already run can tell
+     * that untrusted content entered the context, without matching on a name.
+     */
+    trust?: Trust;
+    /** What this call itself cost, when the tool declared how to read it. */
+    costMicros?: number;
+    /**
+     * Where the content came from, when the tool returned it apart from the prose.
+     *
+     * A search tool already knows each result's url; rendering the output flattens
+     * that into text nobody downstream can read back. Carried here so a citation
+     * survives as a link rather than as something to parse out of a paragraph.
+     */
+    sources?: Source[];
+    /**
+     * Set when the output was cut to fit, with what it was cut from.
+     *
+     * Present only when something was actually dropped, so its absence is the
+     * claim that the output is whole.
+     */
+    truncated?: {
+        kept: number;
+        of: number;
+    };
+    /**
+     * Set when this exact destructive call had already run and the earlier result
+     * was handed back instead of running it again.
+     *
+     * The output is the first call's, unchanged, because it is still true — the
+     * refund did happen. This is for whoever counts how often the agent asked
+     * twice, which is a fact about the agent and not about the answer.
+     */
+    repeated?: true;
 }

package/dist/types/tool.d.ts

@@ -66,6 +66,22 @@ export type ArgsOf<T extends readonly ArgSpec[]> = {
  * the same as safe.
  */
 export type Effect = "readonly" | "idempotent" | "destructive";
+/**
+ * Where what a tool returns came from.
+ *
+ * `own` is yours: a database you run, a file you wrote, a calculation. `external`
+ * is content from outside that somebody else can write — a fetched page, a
+ * search result, an inbox, a document a customer uploaded. What comes back from
+ * one of those is data, and anything in it that reads like an instruction was
+ * put there by whoever controls the source.
+ *
+ * Declared rather than inferred, and separate from `effect`, because the two are
+ * independent: reading a web page is `readonly` and `external`, reading your own
+ * ledger is `readonly` and `own`, and only the first can carry an instruction
+ * written by a stranger. Unset means nobody has said, which is not the same as
+ * safe.
+ */
+export type Trust = "own" | "external";
 /**
  * A description the model reads and a function you wrote, in one object.
  *
@@ -90,6 +106,19 @@ export interface Tool<Args = Record<string, unknown>> {
      * where the words a caller actually types are declared.
      */
     aliases?: string[];
+    /**
+     * A second, differently-shaped input the tool would rather be given, named.
+     *
+     * A stage hands every tool the one question it wrote. That suits a search
+     * engine and defeats a catalogue that matches on a title: measured against
+     * OpenAlex, a 280-character sub-question found nothing where the same ask as
+     * an 80-character phrase found ten papers. Declaring it here is what lets the
+     * stage be told to write one, without the stored wording naming any tool.
+     */
+    wants?: {
+        name: string;
+        description: string;
+    };
     /**
      * Offered whatever selection decides — an escalation path, a refusal, where
      * losing a similarity search is not an acceptable outcome.
@@ -97,6 +126,51 @@ export interface Tool<Args = Record<string, unknown>> {
     pinned?: boolean;
     /** What calling it does outside the process. Unset means unknown. */
     effect?: Effect;
+    /**
+     * Whether what it returns is content somebody outside wrote. Unset means unknown.
+     *
+     * A guard that wants to say "no destructive call after untrusted content came
+     * in" has to gate on something the tool declared. Without this the only thing
+     * left to gate on is the tool's name, which the hook documentation warns
+     * against for the reason it always does: a rename turns the rule off, silently
+     * and in the permissive direction.
+     */
+    trust?: Trust;
+    /**
+     * Reads what one call cost, in micro-USD, out of what `run` returned.
+     *
+     * Some tools spend money: a deep recall runs model calls of its own, a judge
+     * tool pays for a verdict, a sub-agent tool pays for a whole run. That spend
+     * is invisible to the loop that called them — token counts belong to the
+     * outer model call and a tool's own bill is not in them. Without this the
+     * number exists only inside the stringified result, where the model reads it
+     * and no code can add it up.
+     *
+     * A reader rather than a field on the result, because `run` returns whatever
+     * suits the tool and only the tool knows which part of it is the price.
+     */
+    costOf?(value: unknown): number | undefined;
+    /**
+     * Tools that have to be offered alongside this one, or not at all.
+     *
+     * Selection scores each tool on its own, which is the wrong unit when two of
+     * them are a cheap entry point and its expensive counterpart. `deep_recall`
+     * and `recall` overlap on almost every term, so a shortlist of three routinely
+     * kept the dear one and dropped the cheap one — while both descriptions tell
+     * the model to try the cheap one first. The model was then instructed to
+     * prefer a tool it had not been given.
+     *
+     * Enforced as a guarantee rather than a preference: where the shortlist has
+     * no room for the pair, the tool that declared the need is dropped instead.
+     * Offering the expensive half alone is the failure this exists to stop, and a
+     * best-effort version would still do it whenever the ceiling was tight.
+     *
+     * A name no tool on the bus carries is ignored rather than refused. The
+     * constraint is about what a shortlist offers, and a partner that is not on
+     * the bus cannot be dropped in favour of anything — a bus holding this tool
+     * alone has no selection problem to have.
+     */
+    needs?: readonly string[];
     run(args: Args): Promise<unknown> | unknown;
 }
 /** A tool as the model sees it: no implementation, no pin. */

package/docs/bogus.mdx

@@ -0,0 +1,85 @@
+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

@@ -0,0 +1,217 @@
+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

@@ -0,0 +1,90 @@
+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.