@spendgraph/tools 0.5.0 → 0.7.0

package/dist/builtin/wikidata/wikidata.js

@@ -0,0 +1 @@
+import{tool as w}from"../../tool/index.js";import{wikidataApi as b}from"./api.js";import{factsOf as g,referenced as k,rendered as y,statementsOf as x}from"./render.js";const E=30;function L(t){const a=t.indexOf(":");if(a<1)return{name:t.trim(),about:null};const o=t.slice(a+1).trim();return{name:t.slice(0,a).trim(),about:o||null}}function A(t,a){const o=a.toLowerCase().split(/\s+/).filter(Boolean);return t.filter(i=>{const r=i.property.toLowerCase();return o.some(n=>r.includes(n))})}function $(t={}){const a=t.api??b(t),o=t.maxFacts??E;return w({name:"wikidata",effect:"readonly",trust:"external",description:"Looks a thing up on Wikidata and returns what is recorded about it as plain text: what it is, when it began, where it is, who runs it, and so on. Name the thing \u2014 a company, person, place, product or event \u2014 and add ': ' and a topic to narrow it, as in 'Cloudflare: founded' or 'Paris: population'. Not for prices, versions or news.",args:[{name:"question",type:"string",required:!0,maxLength:200,description:"The thing's name, optionally followed by ': ' and what about it."}],run:async({question:i})=>{const{name:r,about:n}=L(i);if(!r)throw new Error("Name the thing to look up.");const s=await a.search(r);if(!s)throw new Error(`Wikidata has nothing named "${r}".`);const e=await a.entity(s.id);if(!e)throw new Error(`Wikidata has no record for ${s.id}.`);const c=x(e).slice(0,o),f=c.flatMap(([p,m])=>[p,...m.flatMap(h=>k(h.mainsnak))]),u=await a.labels(f),d=g(c,u),l=n?A(d,n):d;if(n&&l.length===0)throw new Error(`Wikidata records nothing about "${n}" for ${e.label}.`);return y(e,l)}})}export{$ as wikidata};

package/dist/bus/args.d.ts

@@ -0,0 +1,11 @@
+import type { ArgSpec } from "../types/index.js";
+/**
+ * The arguments a handler is given: declared defaults filled in, and every
+ * declared value at its declared type.
+ *
+ * Validation runs before this and on the raw arguments, so what is required
+ * stays required — a `default` fills a gap, it does not satisfy a demand.
+ * Anything the tool did not declare is passed through untouched: the model may
+ * have sent it, and dropping it would be this package deciding it knows better.
+ */
+export declare function readyArgs(specs: readonly ArgSpec[], args: Record<string, unknown>): Record<string, unknown>;

package/dist/bus/args.js

@@ -0,0 +1 @@
+import{isMissing as s,toBoolean as c,toNumber as f}from"@spendgraph/sdk";function i(e,n){switch(e.type){case"number":return f(n);case"boolean":return c(n);case"list":return Array.isArray(n)?n.map(String):n;case"json":return n;default:return String(n)}}function a(e,n){const t={...n};for(const r of e){const o=t[r.name];if(s(o)){if(r.default===void 0)continue;t[r.name]=i(r,r.default);continue}t[r.name]=i(r,o)}return t}export{a as readyArgs};

package/dist/bus/bus.d.ts

@@ -1,6 +1,7 @@
 import type { RolloutStep } from "@spendgraph/sdk";
-import type { Effect, Tool, ToolDeclaration, ToolResult } from "../types/index.js";
+import type { Effect, Tool, ToolDeclaration, ToolResult, Trust } from "../types/index.js";
 import { type AnthropicTool, type OpenAITool } from "../wire/index.js";
+import type { Offering } from "./only.js";
 import type { ToolBusOptions } from "./options.js";
 import { type ToolTrace } from "./trace.js";
 /**
@@ -32,6 +33,8 @@ export declare function toolbus(tools: Tool<never>[], opts?: ToolBusOptions): {
      * `readonly` — nothing has claimed that.
      */
     effectOf: (name: string) => Effect | undefined;
+    /** What a tool declared about where its content comes from. Unset means unknown. */
+    trustOf: (name: string) => Trust | undefined;
     /**
      * Names of the tools declared `destructive`.
      *
@@ -72,5 +75,24 @@ export declare function toolbus(tools: Tool<never>[], opts?: ToolBusOptions): {
     step: (result: ToolResult, index: number) => RolloutStep;
     /** One turn's tool use, selected once and recorded for the rollout. */
     trace: (query?: string, limit?: number) => ToolTrace;
+    /**
+     * The same bus, offering only these tools.
+     *
+     * What progressive disclosure needs: a model is shown the handful this turn
+     * is about while everything else stays reachable. Declaring fifty tools
+     * costs their whole schema on every call before anyone has said anything,
+     * and the cost is not only tokens — a shortlist is chosen from more
+     * accurately than a shelf.
+     *
+     * A view rather than a second bus. `invoke` still goes through this one, so
+     * usage, the output cap and a once-each memory stay the ones the caller
+     * configured — a `toolbus` rebuilt over a filtered list looks identical and
+     * quietly keeps its own, including a fresh record of which destructive
+     * calls have already run.
+     *
+     * Names it does not have are ignored, the way selection ignores a term it
+     * cannot match.
+     */
+    only: (names: string[]) => Offering;
 };
 export type ToolBus = ReturnType<typeof toolbus>;

package/dist/bus/bus.js

@@ -1,49 +1 @@
-import { toAnthropic, toMarkdown, toOpenAI, } from "../wire/index.js";
-import { invokeTool } from "./invoke.js";
-import { warnOnOverlap } from "./overlap.js";
-import { selectTools } from "./select.js";
-import { toStep } from "./step.js";
-import { newTrace } from "./trace.js";
-export function toolbus(tools, opts = {}) {
-    const now = opts.now ?? (() => Date.now());
-    const ceiling = Math.max(1, opts.limit ?? 6);
-    const byName = new Map();
-    for (const t of tools) {
-        if (byName.has(t.name))
-            throw new Error(`Two tools are called "${t.name}".`);
-        byName.set(t.name, t);
-    }
-    const calls = new Map();
-    if (opts.warnOnOverlap ?? true)
-        warnOnOverlap([...byName.values()]);
-    const declare = (t) => ({
-        name: t.name,
-        description: t.description,
-        args: t.args,
-        ...(t.effect ? { effect: t.effect } : {}),
-    });
-    const all = () => [...byName.values()].map(declare);
-    const bus = {
-        all: () => [...byName.values()],
-        missing: (names) => names.filter((n) => !byName.has(n)),
-        get: (name) => byName.get(name),
-        effectOf: (name) => byName.get(name)?.effect,
-        destructive: () => [...byName.values()].filter((t) => t.effect === "destructive").map((t) => t.name),
-        unannotated: () => [...byName.values()].filter((t) => t.effect === undefined).map((t) => t.name),
-        declarations: (names) => names
-            ? names
-                .map((n) => byName.get(n))
-                .filter(Boolean)
-                .map((t) => declare(t))
-            : all(),
-        anthropic: (decls) => toAnthropic(decls ?? all()),
-        openai: (decls) => toOpenAI(decls ?? all()),
-        markdown: (decls, heading) => toMarkdown(decls ?? all(), heading),
-        select: (query = "", limit) => selectTools([...byName.values()], calls, declare, query, Math.max(1, limit ?? ceiling)),
-        invoke: (name, args) => invokeTool(byName, calls, now, name, args),
-        usage: () => Object.fromEntries(calls),
-        step: (result, index) => toStep(result, index),
-        trace: (query = "", limit) => newTrace(bus.select(query, limit), (name, args) => bus.invoke(name, args)),
-    };
-    return bus;
-}
+import{toAnthropic as g,toMarkdown as h,toOpenAI as O}from"../wire/index.js";import{invokeTool as M}from"./invoke.js";import{onceEach as x}from"./once.js";import{warnOnOverlap as A}from"./overlap.js";import{scorerFor as F}from"./score.js";import{selectTools as k}from"./select.js";import{toStep as j}from"./step.js";import{ceilingFor as u}from"./terms.js";import{newTrace as b}from"./trace.js";function G(y,i={}){const E=i.now??(()=>Date.now()),d=u(i.limit,6),o=new Map;for(const e of y){if(o.has(e.name))throw new Error(`Two tools are called "${e.name}".`);o.set(e.name,e)}const f=new Map;(i.warnOnOverlap??!0)&&A([...o.values()]);const w=F([...o.values()]),v=i.onceEach?x():{earlier:()=>{},keep:()=>{}},c=e=>({name:e.name,description:e.description,args:e.args,...e.aliases?.length?{aliases:e.aliases}:{},...e.effect?{effect:e.effect}:{}}),m=()=>[...o.values()].map(c),l={all:()=>[...o.values()],missing:e=>e.filter(t=>!o.has(t)),get:e=>o.get(e),effectOf:e=>o.get(e)?.effect,trustOf:e=>o.get(e)?.trust,destructive:()=>[...o.values()].filter(e=>e.effect==="destructive").map(e=>e.name),unannotated:()=>[...o.values()].filter(e=>e.effect===void 0).map(e=>e.name),declarations:e=>e?e.map(t=>o.get(t)).filter(Boolean).map(t=>c(t)):m(),anthropic:e=>g(e??m()),openai:e=>O(e??m()),markdown:(e,t)=>h(e??m(),t),select:(e="",t)=>k([...o.values()],f,c,w,e,u(t,d)),invoke:async(e,t)=>{const n=v.earlier(o.get(e),e,t);if(n)return{...n,repeated:!0};const s=await M(o,f,E,e,t,i.maxOutputChars);return v.keep(o.get(e),s),s},usage:()=>Object.fromEntries(f),step:(e,t)=>j(e,t),trace:(e="",t)=>b(l.select(e,t),(n,s)=>l.invoke(n,s)),only:e=>{const t=e.map(r=>o.get(r)).filter(r=>r!==void 0),n=()=>t.map(c),s={...l,all:()=>[...t],missing:r=>r.filter(a=>!t.some(p=>p.name===a)),declarations:r=>r?n().filter(a=>r.includes(a.name)):n(),anthropic:r=>g(r??n()),openai:r=>O(r??n()),markdown:(r,a)=>h(r??n(),a),select:(r="",a)=>k(t,f,c,w,r,u(a,d)),trace:(r="",a)=>b(s.select(r,a),(p,T)=>l.invoke(p,T))};return s}};return l}export{G as toolbus};

package/dist/bus/group.d.ts

@@ -0,0 +1,21 @@
+import type { ToolBus } from "./bus.js";
+import { type Namespacing } from "./namespace.js";
+import type { ToolBusOptions } from "./options.js";
+export interface BusMember {
+    name: string;
+    description: string;
+    bus: ToolBus;
+}
+export interface BusGroupOptions extends ToolBusOptions {
+    /**
+     * Name every tool after the bus that runs it — `billing__search`.
+     *
+     * Without it two buses offering the same tool name is refused, on the
+     * grounds that a name has to say which one runs. That is the right default
+     * for tools you wrote and the wrong one for servers you did not: `search` is
+     * the commonest tool name there is, and a group that will not start is worse
+     * than one that disambiguates. Pass a function to name them yourself.
+     */
+    namespace?: Namespacing;
+}
+export declare function busgroup(members: BusMember[], opts?: BusGroupOptions): ToolBus;

package/dist/bus/group.js

@@ -0,0 +1 @@
+import{toAnthropic as T,toMarkdown as b,toOpenAI as E}from"../wire/index.js";import{naming as N}from"./namespace.js";import{scorerFor as I}from"./score.js";import{toStep as S}from"./step.js";import{ceilingFor as $,termsIn as A}from"./terms.js";import{newTrace as j}from"./trace.js";const C=6,x=3;function L(r){return{name:r.name,description:r.description,args:[]}}function G(r,f){const a=new Map;for(const o of r)for(const c of o.bus.all()){const l=f.offered(o,c.name),w=a.get(l);if(w)throw new Error(`Two buses offer a tool called "${l}": "${w.name}" and "${o.name}". A name has to say which one runs \u2014 set \`namespace\` to name them after their bus.`);a.set(l,o)}return a}function U(r,f){return r.flatMap(a=>{const o=a.bus.all().filter(c=>c.pinned).map(c=>c.name);return o.length>0?v(a,f,a.bus.declarations(o)):[]})}const v=(r,f,a)=>a.map(o=>({...o,name:f.offered(r,o.name)}));function _(r){const f=[],a=new Set;let o=r;return{chosen:f,holds:c=>a.has(c),full:()=>f.length>=o,room:()=>r-f.length,narrowTo:c=>{o=Math.min(o,c)},take(c){a.has(c.name)||f.length>=o||(a.add(c.name),f.push(c))}}}function K(r,f,a){const o=r.flat(),c=I(o),l=o.map(d=>({declaration:d,n:c(d,f)})).sort((d,O)=>O.n-d.n);if(l.length===0||l[0].n===0)return!1;l.length>1&&l[0].n>=l[1].n*2&&a.narrowTo(a.chosen.length+x);for(const{declaration:d}of l){if(a.full())break;a.take(d)}return!0}function P(r,f){for(let a=0;!f.full();a++){let o=!1;for(const c of r){const l=c[a];if(l!==void 0&&(o=!0,f.take(l),f.full()))break}if(!o)break}}function W(r,f={}){const a=new Set;for(const n of r){if(a.has(n.name))throw new Error(`Two buses are called "${n.name}".`);a.add(n.name)}const o=N(r,f.namespace),c=G(r,o),l=U(r,o),w=new Map(r.map(n=>[n,L(n)])),d=I([...w.values()]),O=$(f.limit,C),m=n=>c.get(n),g=(n,t)=>o.owned(n,t),y=()=>r.flatMap(n=>n.bus.all().map(t=>({...t,name:o.offered(n,t.name)}))),k=()=>r.flatMap(n=>v(n,o,n.bus.declarations())),B=(n,t)=>Object.fromEntries(Object.entries(t).map(([e,u])=>[o.offered(n,e),u])),D=n=>r.map(t=>({member:t,n:d(w.get(t),n)})).sort((t,e)=>e.n-t.n),h={all:y,missing:n=>n.filter(t=>!c.has(t)),get:n=>{const t=m(n),e=t?.bus.get(g(t,n));return e&&t?{...e,name:n}:e},effectOf:n=>{const t=m(n);return t?.bus.effectOf(g(t,n))},trustOf:n=>{const t=m(n);return t?.bus.trustOf(g(t,n))},destructive:()=>r.flatMap(n=>n.bus.destructive().map(t=>o.offered(n,t))),unannotated:()=>r.flatMap(n=>n.bus.unannotated().map(t=>o.offered(n,t))),declarations:n=>n?r.flatMap(t=>{const e=n.filter(s=>c.get(s)===t);if(e.length===0)return[];const u=e.map(s=>g(t,s));return v(t,o,t.bus.declarations(u))}):k(),anthropic:n=>T(n??k()),openai:n=>E(n??k()),markdown:(n,t)=>b(n??k(),t),select:(n="",t)=>{const e=_($(t,O));for(const p of l)e.take(p);const u=e.room();if(u<=0)return e.chosen;const s=D(A(n)),i=s.map(({member:p})=>v(p,o,p.bus.select(n,u)).filter(F=>!e.holds(F.name)));if(s.length>1&&s[0].n>0&&s[0].n>=s[1].n*2&&i[0].length>0){e.narrowTo(e.chosen.length+x);for(const p of i[0])e.take(p);return e.chosen}return K(i,A(n),e)||P(i,e),e.chosen},invoke:async(n,t)=>{const e=m(n);return e?{...await e.bus.invoke(g(e,n),t),name:n}:{name:n,args:t,status:"failed",output:"",error:`No tool called "${n}". Offered: ${[...c.keys()].join(", ")}`,latencyMs:0}},usage:()=>Object.assign({},...r.map(n=>B(n,n.bus.usage()))),step:(n,t)=>S(n,t),trace:(n="",t)=>j(h.select(n,t),(e,u)=>h.invoke(e,u)),only:n=>{const t=n.filter(s=>c.has(s)),e=()=>h.declarations(t),u={...h,all:()=>y().filter(s=>t.includes(s.name)),missing:s=>s.filter(i=>!t.includes(i)),declarations:s=>s?e().filter(i=>s.includes(i.name)):e(),anthropic:s=>T(s??e()),openai:s=>E(s??e()),markdown:(s,i)=>b(s??e(),i),select:(s="",i)=>h.select(s,i).filter(M=>t.includes(M.name)),trace:(s="",i)=>j(u.select(s,i),(M,p)=>h.invoke(M,p))};return u}};return h}export{W as busgroup};

package/dist/bus/index.d.ts

@@ -1,3 +1,7 @@
 export { type ToolBus, toolbus } from "./bus.js";
+export { type BusGroupOptions, type BusMember, busgroup } from "./group.js";
+export type { Namespacing } from "./namespace.js";
+export type { Offering } from "./only.js";
 export type { ToolBusOptions } from "./options.js";
+export { priced, spentOn } from "./spent.js";
 export { newTrace, type ToolTrace } from "./trace.js";

package/dist/bus/index.js

@@ -1,2 +1 @@
-export { toolbus } from "./bus.js";
-export { newTrace } from "./trace.js";
+import{toolbus as e}from"./bus.js";import{busgroup as t}from"./group.js";import{priced as m,spentOn as x}from"./spent.js";import{newTrace as s}from"./trace.js";export{t as busgroup,s as newTrace,m as priced,x as spentOn,e as toolbus};

package/dist/bus/invoke.d.ts

@@ -6,4 +6,4 @@ import type { Tool, ToolResult } from "../types/index.js";
  * step worth recording, not an exception that ends the run — the same argument
  * `status` and `error` exist on a rollout for.
  */
-export declare function invokeTool(byName: Map<string, Tool<never>>, calls: Map<string, number>, now: () => number, name: string, args: Record<string, unknown>): Promise<ToolResult>;
+export declare function invokeTool(byName: Map<string, Tool<never>>, calls: Map<string, number>, now: () => number, name: string, args: Record<string, unknown>, maxOutputChars?: number): Promise<ToolResult>;

package/dist/bus/invoke.js

@@ -1,43 +1,3 @@
-import { FieldValidationError, validateFields } from "@spendgraph/sdk";
-export async function invokeTool(byName, calls, now, name, args) {
-    const started = now();
-    const found = byName.get(name);
-    const base = { name, args, latencyMs: 0 };
-    if (!found) {
-        return {
-            ...base,
-            status: "failed",
-            output: "",
-            error: `No tool called "${name}". Offered: ${[...byName.keys()].join(", ")}`,
-        };
-    }
-    const errors = validateFields(args, found.args);
-    if (errors.length > 0) {
-        return {
-            ...base,
-            status: "failed",
-            output: "",
-            error: new FieldValidationError(errors).message,
-            latencyMs: now() - started,
-        };
-    }
-    calls.set(name, (calls.get(name) ?? 0) + 1);
-    try {
-        const value = await found.run(args);
-        return {
-            ...base,
-            status: "completed",
-            output: typeof value === "string" ? value : JSON.stringify(value),
-            latencyMs: now() - started,
-        };
-    }
-    catch (err) {
-        return {
-            ...base,
-            status: "failed",
-            output: "",
-            error: err instanceof Error ? err.message : "Tool failed.",
-            latencyMs: now() - started,
-        };
-    }
-}
+import{FieldValidationError as d,validateFields as y}from"@spendgraph/sdk";import{readyArgs as g}from"./args.js";import{reasonFor as h,render as p}from"./output.js";function M(r,e){if(e===void 0||r.length<=e)return{output:r};const t=Math.max(0,e);return{output:`${r.slice(0,t)}
+
+[cut: showing the first ${t} of ${r.length} characters]`,truncated:{kept:t,of:r.length}}}function $(r){const e=r?.results;if(!Array.isArray(e))return{};const t=e.filter(s=>!!s&&typeof s.url=="string"&&s.url!=="");return t.length?{sources:t}:{}}function k(r,e){if(!r.costOf)return{};try{const t=r.costOf(e);return typeof t=="number"&&Number.isFinite(t)&&t>=0?{costMicros:t}:{}}catch{return{}}}async function A(r,e,t,s,u,f){const i=t(),n=r.get(s),c={name:s,args:u,latencyMs:0,...n?.trust?{trust:n.trust}:{}};if(!n)return{...c,status:"failed",output:"",error:`No tool called "${s}". Offered: ${[...r.keys()].join(", ")}`};const a=y(u,n.args);if(a.length>0)return{...c,status:"failed",output:"",error:new d(a).message,latencyMs:t()-i};e.set(s,(e.get(s)??0)+1);const l=g(n.args,u);try{const o=await n.run(l);return{...c,status:"completed",...M(p(o),f),latencyMs:t()-i,...k(n,o),...$(o)}}catch(o){return{...c,status:"failed",output:"",error:h(o),latencyMs:t()-i}}}export{A as invokeTool};

package/dist/bus/namespace.d.ts

@@ -0,0 +1,21 @@
+import type { BusMember } from "./group.js";
+/** How a grouped tool is named to the model. */
+export type Namespacing = boolean | ((member: string, tool: string) => string);
+export interface Naming {
+    /** What the model is offered, given a tool's own name on its bus. */
+    offered(member: BusMember, tool: string): string;
+    /** Back to the name the owning bus knows, given a name the model used. */
+    owned(member: BusMember, offered: string): string;
+}
+/**
+ * Names every tool after the bus that runs it, or leaves them all alone.
+ *
+ * Off by default, because a name that says nothing about who runs it is a name
+ * worth fixing at the source. It is not always yours to fix: a group standing
+ * in front of several servers you do not own will meet two of them offering
+ * `search`, and refusing to start is not better than disambiguating.
+ *
+ * Built eagerly from what each bus holds, so the reverse lookup is complete
+ * before the first call rather than filled in as names happen to be asked for.
+ */
+export declare function naming(members: BusMember[], how: Namespacing | undefined): Naming;

package/dist/bus/namespace.js

@@ -0,0 +1 @@
+const d="__",p=(o,t)=>`${o}__${t}`;function u(o,t){if(!t)return{offered:(n,e)=>e,owned:(n,e)=>e};const r=typeof t=="function"?t:p,m=new Map,s=new Map;for(const n of o){const e=new Map,f=new Map;for(const a of n.bus.all()){const c=r(n.name,a.name);e.set(a.name,c),f.set(c,a.name)}m.set(n.name,e),s.set(n.name,f)}return{offered:(n,e)=>m.get(n.name)?.get(e)??e,owned:(n,e)=>s.get(n.name)?.get(e)??e}}export{u as naming};

package/dist/bus/once.d.ts

@@ -0,0 +1,32 @@
+import type { Tool, ToolResult } from "../types/index.js";
+/**
+ * The same call again: the tool, and the arguments in a stable order.
+ *
+ * Sorted, because a model writing `{invoice, amount}` on one turn and
+ * `{amount, invoice}` on the next means the same call, and a key that said
+ * otherwise would let the second one through — which is the whole failure.
+ */
+export declare const callKey: (name: string, args: Record<string, unknown>) => string;
+/**
+ * Remembers what each destructive call already did, so a repeat does not do it twice.
+ *
+ * The agent runtime retries — after a timeout, a crash, a redelivery — and that
+ * is correct; the tool layer is where a repeat has to stop being a second
+ * refund. `effect` has always said which calls need this and nothing has ever
+ * read it: `destructive` is precisely the label for a call that is not safe to
+ * repeat, and `idempotent` is the label for one that is.
+ *
+ * Only completed calls are remembered. A failed one is exactly what a retry is
+ * for, and refusing to try again because the first attempt fell over would turn
+ * every transient error into a permanent one.
+ *
+ * A tool that declared no effect is not covered. Unset means nobody has said,
+ * which is not the same as safe — the package cannot invent the label, and
+ * quietly deduplicating an unlabelled call would be a guess about somebody
+ * else's API.
+ */
+export declare function onceEach(): {
+    /** The earlier result for this exact destructive call, when there is one. */
+    earlier(tool: Tool<never> | undefined, name: string, args: Record<string, unknown>): ToolResult | undefined;
+    keep(tool: Tool<never> | undefined, result: ToolResult): void;
+};

package/dist/bus/once.js

@@ -0,0 +1 @@
+const r=t=>{if(t===null||typeof t!="object")return JSON.stringify(t)??"";if(Array.isArray(t))return`[${t.map(r).join(",")}]`;const n=t;return`{${Object.keys(n).sort().map(e=>`${JSON.stringify(e)}:${r(n[e])}`).join(",")}}`},c=(t,n)=>`${t}::${r(n)}`;function o(){const t=new Map;return{earlier(n,e,i){if(n?.effect==="destructive")return t.get(c(e,i))},keep(n,e){n?.effect!=="destructive"||e.status!=="completed"||t.set(c(e.name,e.args),e)}}}export{c as callKey,o as onceEach};

package/dist/bus/only.d.ts

@@ -0,0 +1,29 @@
+import type { Effect, Tool, ToolDeclaration, ToolResult } from "../types/index.js";
+import type { AnthropicTool, OpenAITool } from "../wire/index.js";
+import type { ToolTrace } from "./trace.js";
+/**
+ * A bus narrowed to some of its tools.
+ *
+ * The declaring half is the half that changes: a model is shown these, and
+ * everything reaches the same `invoke` underneath. Written out rather than
+ * derived from `toolbus`, because a type that referred back to its own return
+ * would be circular — and because what a view promises is worth saying once.
+ */
+export interface Offering {
+    /** The tools in this view, in declaration order. */
+    all(): Tool<never>[];
+    get(name: string): Tool<never> | undefined;
+    /** Names this view does not offer, whether or not the bus behind it has them. */
+    missing(names: string[]): string[];
+    effectOf(name: string): Effect | undefined;
+    declarations(names?: string[]): ToolDeclaration[];
+    anthropic(decls?: ToolDeclaration[]): AnthropicTool[];
+    openai(decls?: ToolDeclaration[]): OpenAITool[];
+    markdown(decls?: ToolDeclaration[], heading?: string): string;
+    select(query?: string, limit?: number): ToolDeclaration[];
+    /** Runs one, through the bus this view came from. */
+    invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /** How often each has been called on the bus behind this view. */
+    usage(): Record<string, number>;
+    trace(query?: string, limit?: number): ToolTrace;
+}

package/dist/bus/options.d.ts

@@ -19,4 +19,35 @@ export interface ToolBusOptions {
      * often, which is why it is worth saying at construction.
      */
     warnOnOverlap?: boolean;
+    /**
+     * Longest output a tool may return, in characters. No cap by default.
+     *
+     * One tool handing back a whole document fills a window on its own, and the
+     * failure is silent: no error, a clean call, a clean reply, and an answer
+     * that is wrong in the same tone as a right one. Nothing downstream can tell
+     * a tool that found three matches from one that found three hundred and was
+     * cut after three.
+     *
+     * Cut output says so, twice: a line the model reads at the end of the text,
+     * and `truncated` on the result for code that needs to count it. A model told
+     * it is looking at part of something asks again; one that is not, answers.
+     *
+     * No default, because a cap is a statement about your context window and your
+     * tools, and a number chosen here would be wrong for both. The builtins that
+     * fetch carry their own `maxChars` for the same reason.
+     */
+    maxOutputChars?: number;
+    /**
+     * Run each destructive call once, however many times it is asked for.
+     *
+     * A repeat of a call that already completed gets the first result back
+     * without the tool running again, marked `repeated` so an operator can count
+     * it. `readonly` and `idempotent` calls run every time, which is what those
+     * labels mean; a tool that declared no effect is not covered.
+     *
+     * Off by default. Deduplication is scoped to one bus, so what counts as "the
+     * same call again" is a decision about how long a bus lives — one per run, one
+     * per session, one per process — and the package cannot make it for you.
+     */
+    onceEach?: boolean;
 }

package/dist/bus/options.js

@@ -1 +0,0 @@
-export {};

package/dist/bus/output.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What a handler returned, as the string a result carries.
+ *
+ * A string is itself; anything else is JSON. `graph`'s `stringify` describes
+ * this as "the same convention as a tool result" — it was not, and this is the
+ * side that had drifted.
+ *
+ * `JSON.stringify` returns `undefined` for a function or an undefined value, so
+ * a completed result carried `output: undefined` where its own type says
+ * `string`, and the model was handed nothing while being told it was handed
+ * something. And it *throws* on a circular object, a `BigInt`, or anything whose
+ * `toJSON` throws — a circular object being any value with a parent backlink.
+ *
+ * What comes back when a value cannot be written is a note saying so, never
+ * `""`: an empty output reads as a tool that produced nothing, and this is a
+ * tool that produced something unwritable.
+ */
+export declare function render(value: unknown): string;
+/**
+ * Why a handler failed, from whatever it threw.
+ *
+ * Anything can be thrown, and a string is thrown often enough. Reading only
+ * `Error.message` turned `throw "upstream refused"` into "Tool failed.", which
+ * discards the one thing the tool said about it.
+ */
+export declare function reasonFor(err: unknown): string;

package/dist/bus/output.js

@@ -0,0 +1,2 @@
+function r(n){if(n==null)return"";if(typeof n=="string")return n;try{const t=JSON.stringify(n);return t===void 0?`[not recordable: ${typeof n}]`:t}catch(t){return`[not recordable: ${(t instanceof Error?t.message:String(t)).split(`
+`)[0]}]`}}function o(n){if(n instanceof Error&&n.message.trim())return n.message;if(typeof n=="string"&&n.trim())return n;const t=r(n);return t&&t!=="{}"?`Tool failed: ${t}`:"Tool failed."}export{o as reasonFor,r as render};

package/dist/bus/overlap.js

@@ -1,31 +1 @@
-function words(tool) {
-    return new Set(tool.description
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((w) => w.length > 3));
-}
-export function warnOnOverlap(tools) {
-    const sets = tools.map(words);
-    const named = [];
-    let pairs = 0;
-    for (let i = 0; i < tools.length; i++) {
-        for (let j = i + 1; j < tools.length; j++) {
-            const a = sets[i];
-            const b = sets[j];
-            if (a.size === 0 || b.size === 0)
-                continue;
-            const shared = [...a].filter((w) => b.has(w)).length;
-            if (shared / Math.min(a.size, b.size) < 0.8)
-                continue;
-            pairs += 1;
-            if (named.length < 3)
-                named.push(`"${tools[i].name}" and "${tools[j].name}"`);
-        }
-    }
-    if (pairs === 0)
-        return;
-    const rest = pairs - named.length;
-    console.warn(`[toolbus] ${pairs} ${pairs === 1 ? "pair of tools describes" : "pairs of tools describe"} ` +
-        `themselves almost identically: ${named.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}. ` +
-        `The model will struggle to choose between them — give them distinct descriptions, or merge them.`);
-}
+import{termsIn as h}from"./terms.js";function m(e){return new Set(h(e.description).filter(i=>i.length>3))}function g(e){const i=e.map(m),s=[];let t=0;for(let n=0;n<e.length;n++)for(let r=n+1;r<e.length;r++){const o=i[n],l=i[r];o.size===0||l.size===0||[...o].filter(c=>l.has(c)).length/Math.min(o.size,l.size)<.8||(t+=1,s.length<3&&s.push(`"${e[n].name}" and "${e[r].name}"`))}if(t===0)return;const a=t-s.length;console.warn(`[toolbus] ${t} ${t===1?"pair of tools describes":"pairs of tools describe"} themselves almost identically: ${s.join(", ")}${a>0?`, and ${a} more`:""}. The model will struggle to choose between them \u2014 give them distinct descriptions, or merge them.`)}export{g as warnOnOverlap};

package/dist/bus/score.d.ts

@@ -1,9 +1,11 @@
-import type { Tool } from "../types/index.js";
-/**
- * Overlap between the query and a tool's own words.
- *
- * The name counts for more than the description: "refund" in a question is a
- * stronger signal about the `refund` tool than the same word buried in a
- * paragraph about it.
- */
-export declare function score(tool: Tool<never>, terms: string[]): number;
+export interface Describable {
+    name: string;
+    description: string;
+    args: readonly {
+        name: string;
+        description?: string;
+    }[];
+    aliases?: readonly string[];
+}
+export type Scorer = (subject: Describable, terms: string[]) => number;
+export declare function scorerFor(corpus: readonly Describable[]): Scorer;

package/dist/bus/score.js

@@ -1,12 +1 @@
-export function score(tool, terms) {
-    const name = tool.name.toLowerCase().replace(/_/g, " ");
-    const body = `${tool.description} ${tool.args.map((a) => `${a.name} ${a.description ?? ""}`).join(" ")}`.toLowerCase();
-    let n = 0;
-    for (const term of terms) {
-        if (name.includes(term))
-            n += 3;
-        else if (body.includes(term))
-            n += 1;
-    }
-    return n;
-}
+import{termsIn as l}from"./terms.js";const h=3,m=2,w=1,d=new WeakMap,a=n=>new Set(l(n));function g(n){const t=d.get(n);if(t)return t;const r={name:a(n.name.replace(/_/g," ")),aliases:a((n.aliases??[]).join(" ")),body:a(`${n.description} ${n.args.map(o=>`${o.name} ${o.description??""}`).join(" ")}`)};return d.set(n,r),r}function p(n,t){return n.name.has(t)?h:n.aliases.has(t)?m:n.body.has(t)?w:0}function I(n){const t=new Map;for(const o of n){const e=g(o);for(const s of new Set([...e.name,...e.aliases,...e.body]))t.set(s,(t.get(s)??0)+1)}const r=o=>Math.log((n.length+1)/((t.get(o)??0)+.5));return(o,e)=>{const s=g(o);let i=0;for(const c of e){const f=p(s,c);f>0&&(i+=f*r(c))}return i}}export{I as scorerFor};

package/dist/bus/select.d.ts

@@ -1,18 +1,3 @@
 import type { Tool, ToolDeclaration } from "../types/index.js";
-/**
- * The working set for one request: pinned, then what the query matches, then
- * what actually gets used.
- *
- * Relevance before usage, which is the opposite of what this did first. At a
- * shortlist of twelve the order was harmless; at six, three previously-used
- * tools take half the slots and push out the tool the query needs.
- *
- * Usage still 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.
- *
- * How many come back depends on how clearly the query matched. A single strong
- * match needs no company; a flat spread means the ranking does not know, and a
- * wider net is worth the distraction.
- */
-export declare function selectTools(tools: Tool<never>[], calls: Map<string, number>, declare: (t: Tool<never>) => ToolDeclaration, query: string, ceiling: number): ToolDeclaration[];
+import type { Scorer } from "./score.js";
+export declare function selectTools(tools: Tool<never>[], calls: Map<string, number>, declare: (t: Tool<never>) => ToolDeclaration, scoreOf: Scorer, query: string, ceiling: number): ToolDeclaration[];

package/dist/bus/select.js

@@ -1,44 +1 @@
-import { score } from "./score.js";
-export function selectTools(tools, calls, declare, query, ceiling) {
-    const terms = query
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter(Boolean);
-    const chosen = [];
-    const take = (t) => {
-        if (!chosen.includes(t) && chosen.length < ceiling)
-            chosen.push(t);
-    };
-    for (const t of tools)
-        if (t.pinned)
-            take(t);
-    const rest = tools.filter((t) => !t.pinned);
-    const ranked = rest
-        .map((t) => ({ t, n: score(t, terms) }))
-        .filter((x) => x.n > 0)
-        .sort((a, b) => b.n - a.n || (calls.get(b.t.name) ?? 0) - (calls.get(a.t.name) ?? 0));
-    const room = ceiling - chosen.length;
-    const decisive = ranked.length > 1 && ranked[0].n >= ranked[1].n * 2;
-    const budget = chosen.length + (decisive ? Math.min(3, room) : room);
-    for (const { t } of ranked) {
-        if (chosen.length >= budget)
-            break;
-        take(t);
-    }
-    const byUse = [...rest].sort((a, b) => (calls.get(b.name) ?? 0) - (calls.get(a.name) ?? 0));
-    for (const t of byUse) {
-        if (chosen.length >= budget)
-            break;
-        if ((calls.get(t.name) ?? 0) === 0)
-            break;
-        take(t);
-    }
-    if (ranked.length === 0) {
-        for (const t of rest) {
-            if (chosen.length >= ceiling)
-                break;
-            take(t);
-        }
-    }
-    return chosen.map(declare);
-}
+import{termsIn as l}from"./terms.js";function w(t,o,g){if(!t.some(f=>f.needs?.length))return t;const r=[];for(const f of t){if(r.includes(f))continue;const s=(f.needs??[]).map(i=>o.get(i)).filter(i=>i!==void 0&&!r.includes(i));r.length+1+s.length>g||r.push(f,...s)}return r}function M(t,o,g,r,f,s){const i=new Map(t.map(n=>[n.name,n])),p=l(f),e=[],m=n=>{!e.includes(n)&&e.length<s&&e.push(n)};for(const n of t)n.pinned&&m(n);const d=t.filter(n=>!n.pinned),c=d.map(n=>({t:n,n:r(n,p)})).filter(n=>n.n>0).sort((n,a)=>a.n-n.n||(o.get(a.t.name)??0)-(o.get(n.t.name)??0)),u=s-e.length,k=c.length>1&&c[0].n>=c[1].n*2,h=e.length+(k?Math.min(3,u):u);for(const{t:n}of c){if(e.length>=h)break;m(n)}const b=[...d].sort((n,a)=>(o.get(a.name)??0)-(o.get(n.name)??0));for(const n of b){if(e.length>=h||(o.get(n.name)??0)===0)break;m(n)}if(c.length===0)for(const n of d){if(e.length>=s)break;m(n)}return w(e,i,s).map(g)}export{M as selectTools};

package/dist/bus/spent.d.ts

@@ -0,0 +1,16 @@
+import type { ToolResult } from "../types/index.js";
+/**
+ * What the tools themselves cost, in micro-USD.
+ *
+ * A run's token counts are the outer model's. A tool that spends on its own —
+ * a deep recall, a judge, a sub-agent — is not in them, so a loop that called
+ * three of those reports a bill that is missing most of itself. Only results
+ * from tools that declared a `costOf` count; the rest are not free, they are
+ * unmeasured, and those are different claims.
+ */
+export declare function spentOn(results: readonly ToolResult[]): number;
+/** The calls that reported a price, so an unmeasured one is visible as an absence. */
+export declare function priced(results: readonly ToolResult[]): {
+    name: string;
+    costMicros: number;
+}[];

package/dist/bus/spent.js

@@ -0,0 +1 @@
+function c(o){let t=0;for(const r of o)t+=r.costMicros??0;return t}function e(o){return o.filter(t=>t.costMicros!==void 0).map(t=>({name:t.name,costMicros:t.costMicros}))}export{e as priced,c as spentOn};

package/dist/bus/step.js

@@ -1,11 +1 @@
-export function toStep(result, index) {
-    return {
-        index,
-        source: result.name,
-        input: result.args,
-        output: result.output,
-        status: result.status,
-        error: result.error,
-        latencyMs: result.latencyMs,
-    };
-}
+function n(t,o){return{index:o,source:t.name,input:t.args,output:t.output,status:t.status,error:t.error,latencyMs:t.latencyMs}}export{n as toStep};

package/dist/bus/terms.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A string as the words selection compares.
+ *
+ * Split on anything that is not a letter or a number **in any script**, rather
+ * than on `[^a-z0-9]`. That was the whole of the tokenizer, so a query with no
+ * ASCII letters produced no terms at all, nothing scored, and every request
+ * fell through to "the first six tools declared" — the same six for "返金して"
+ * as for "верните деньги", whatever the bus held.
+ *
+ * Diacritics are folded so `réfund` and `refund` are one word. Both sides are
+ * folded, so it holds for a tool named in a language that uses them as much as
+ * for a query typed in one.
+ */
+export declare function fold(text: string): string;
+export declare function termsIn(text: string): string[];
+/**
+ * How many tools to offer, from what the caller asked for.
+ *
+ * `NaN` is refused rather than clamped. `Math.max(1, NaN)` is `NaN`, and
+ * `chosen.length < NaN` is false for every length, so a `NaN` ceiling offered
+ * the model **nothing** — the one outcome this file's own reasoning rules out:
+ * "an agent handed no tools cannot act". `Number(process.env.TOOL_LIMIT)` on an
+ * unset variable is how it arrives without anyone typing it.
+ */
+export declare function ceilingFor(limit: number | undefined, fallback: number): number;

package/dist/bus/terms.js

@@ -0,0 +1 @@
+function f(e){return e.toLowerCase().normalize("NFD").replace(/\p{M}+/gu,"")}const r=typeof Intl<"u"&&"Segmenter"in Intl?new Intl.Segmenter(void 0,{granularity:"word"}):void 0;function i(e){const n=f(e);if(!r)return n.split(/[^\p{L}\p{N}]+/u).filter(Boolean);const o=[];for(const t of r.segment(n))t.isWordLike&&o.push(t.segment);return o}function u(e,n){if(e===void 0)return n;if(Number.isNaN(e))throw new Error(`A tool limit of ${e} is not a limit \u2014 nothing would ever be offered. Pass a count, or leave it out for the bus default.`);return Math.max(1,Math.floor(e))}export{u as ceilingFor,f as fold,i as termsIn};

package/dist/bus/trace.d.ts

@@ -18,7 +18,12 @@ export interface ToolTrace {
      * never said — and for one that was never offered.
      */
     effectOf(name: string): Effect | undefined;
-    /** Runs a tool and records the step. Never throws, exactly as `invoke`. */
+    /**
+     * Runs a tool this turn offered and records the step. Never throws.
+     *
+     * A name that was not offered comes back as a failed result naming what was,
+     * without reaching the bus — see `newTrace`.
+     */
     invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
     /** The steps so far, in call order. */
     steps(): RolloutStep[];
@@ -38,5 +43,13 @@ export interface ToolTrace {
  *
  * Selection happens once, here, and the same list is what gets reported. A trace
  * cannot disagree with itself about what the model saw.
+ *
+ * It also cannot run what it did not offer. A shortlist narrows the declarations
+ * and used to hand `invoke` the whole bus, so a name the model produced out of
+ * nowhere still ran if anything on the bus happened to be called that — and the
+ * rollout came back with a step that had no matching entry in `offeredTools`,
+ * which reads as impossible. The refusal is a failed result rather than a throw,
+ * carrying the names that were offered, because that is an observation the model
+ * can correct from on its next turn; an exception is one the run dies of.
  */
 export declare function newTrace(offered: ToolDeclaration[], invoke: (name: string, args: Record<string, unknown>) => Promise<ToolResult>): ToolTrace;