@spendgraph/tools 0.6.0 → 0.8.0

package/dist/builtin/openalex/api.d.ts

@@ -0,0 +1,26 @@
+import { type PaperFilters } from "../../papers/papers.js";
+import { type PoliteOptions } from "../polite.js";
+export interface Paper {
+    title: string;
+    year: number | null;
+    authors: string[];
+    venue: string | null;
+    citations: number;
+    doi: string | null;
+    pdf: string | null;
+    abstract: string;
+}
+export interface Works {
+    papers: Paper[];
+    costMicroUsd?: number;
+}
+export interface OpenAlexApi {
+    search(query: string, limit: number, filters?: PaperFilters): Promise<Works>;
+}
+export interface ApiOptions extends Omit<PoliteOptions, "userAgent" | "headers"> {
+    apiKey?: string;
+}
+/** OpenAlex stores an abstract as word → positions; this puts the words back in order. */
+export declare function abstractOf(index: Record<string, number[]> | null | undefined): string;
+/** The one OpenAlex call the tool makes, behind an interface a test can fake. */
+export declare function openAlexApi(opts?: ApiOptions): OpenAlexApi;

package/dist/builtin/openalex/api.js

@@ -0,0 +1 @@
+import{microUsd as u}from"../../papers/papers.js";import{politeGet as p}from"../polite.js";const d="https://api.openalex.org/works",f="spendgraph-tools (https://spendgraph.locusgraph.com)",_=/[?*]/g;function h(e){return e.replace(_," ").replace(/\s+/g," ").trim()}const m=["id","doi","title","publication_year","cited_by_count","authorships","primary_location","open_access","abstract_inverted_index"].join(",");function y(e){if(!e)return"";const t=[];for(const[n,s]of Object.entries(e))for(const o of s)t[o]=n;return t.filter(n=>n!==void 0).join(" ")}function b(e){return{title:e.title?.trim()||"(untitled)",year:e.publication_year??null,authors:(e.authorships??[]).flatMap(t=>t.author?.display_name?[t.author.display_name]:[]),venue:e.primary_location?.source?.display_name||null,citations:e.cited_by_count??0,doi:e.doi?.replace(/^https?:\/\/doi\.org\//,"")||null,pdf:e.open_access?.oa_url||e.primary_location?.pdf_url||null,abstract:y(e.abstract_inverted_index)}}function g(e){if(!e)return null;const{yearMin:t,yearMax:n,openAccess:s,minCitations:o}=e,r=[t===void 0?null:`publication_year:>${t-1}`,n===void 0?null:`publication_year:<${n+1}`,o===void 0?null:`cited_by_count:>${o-1}`,s?"is_oa:true":null].filter(a=>a!==null);return r.length>0?r.join(","):null}function j(e={}){const t=p({...e,userAgent:f,...e.apiKey?{headers:{authorization:`Bearer ${e.apiKey}`}}:{}});return{async search(n,s,o){const r=new URL(d);r.searchParams.set("search",h(n)),r.searchParams.set("per-page",String(s)),r.searchParams.set("select",m);const a=g(o);a&&r.searchParams.set("filter",a);const i=await t(r);if(!i.ok)throw new Error(`OpenAlex answered ${i.status}.`);const c=await i.json(),l=u(c.meta?.cost_usd);return{papers:(c.results??[]).map(b),...l===void 0?{}:{costMicroUsd:l}}}}}export{y as abstractOf,j as openAlexApi};

package/dist/builtin/openalex/index.d.ts

@@ -0,0 +1,3 @@
+export type { ApiOptions, OpenAlexApi, Paper } from "./api.js";
+export { abstractOf, openAlexApi } from "./api.js";
+export { type OpenAlexOptions, openalex } from "./openalex.js";

package/dist/builtin/openalex/index.js

@@ -0,0 +1 @@
+import{abstractOf as p,openAlexApi as r}from"./api.js";import{openalex as x}from"./openalex.js";export{p as abstractOf,r as openAlexApi,x as openalex};

package/dist/builtin/openalex/openalex.d.ts

@@ -0,0 +1,36 @@
+import { type OpenAlexPapersOptions } from "../../papers/openalex/index.js";
+export interface OpenAlexOptions extends OpenAlexPapersOptions {
+    maxAbstractChars?: number;
+}
+export declare function openalex(opts?: OpenAlexOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "query";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 1000;
+    readonly description: string;
+}, {
+    readonly name: "year_min";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 1500;
+    readonly max: 2200;
+    readonly description: "Earliest year of publication. Leave unset for any.";
+}, {
+    readonly name: "year_max";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 1500;
+    readonly max: 2200;
+    readonly description: "Latest year of publication. Leave unset for any.";
+}, {
+    readonly name: "min_citations";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 0;
+    readonly description: "Only papers cited at least this often. Raises confidence and hides recent work.";
+}, {
+    readonly name: "open_access";
+    readonly type: "boolean";
+    readonly required: false;
+    readonly description: "Only papers whose full text can be read without a subscription.";
+}]>>;

package/dist/builtin/openalex/openalex.js

@@ -0,0 +1 @@
+import{openAlexPapers as e}from"../../papers/openalex/index.js";import{paperSearch as t}from"../paper-search/index.js";const s=5,o=400;function n(r={}){const a=r.maxResults??s;return t({papers:e({...r,maxResults:a}),maxResults:a,maxAbstractChars:r.maxAbstractChars??o})}export{n as openalex};

package/dist/builtin/paper-search/index.d.ts

@@ -0,0 +1 @@
+export { type PaperSearchOptions, paperSearch } from "./paper-search.js";

package/dist/builtin/paper-search/index.js

@@ -0,0 +1 @@
+import{paperSearch as p}from"./paper-search.js";export{p as paperSearch};

package/dist/builtin/paper-search/paper-search.d.ts

@@ -0,0 +1,38 @@
+import { type PaperSearcher } from "../../papers/papers.js";
+export interface PaperSearchOptions {
+    papers: PaperSearcher;
+    maxResults?: number;
+    maxAbstractChars?: number;
+}
+export declare function paperSearch(opts: PaperSearchOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "query";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 1000;
+    readonly description: string;
+}, {
+    readonly name: "year_min";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 1500;
+    readonly max: 2200;
+    readonly description: "Earliest year of publication. Leave unset for any.";
+}, {
+    readonly name: "year_max";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 1500;
+    readonly max: 2200;
+    readonly description: "Latest year of publication. Leave unset for any.";
+}, {
+    readonly name: "min_citations";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 0;
+    readonly description: "Only papers cited at least this often. Raises confidence and hides recent work.";
+}, {
+    readonly name: "open_access";
+    readonly type: "boolean";
+    readonly required: false;
+    readonly description: "Only papers whose full text can be read without a subscription.";
+}]>>;

package/dist/builtin/paper-search/paper-search.js

@@ -0,0 +1,3 @@
+import{DEFAULT_ABSTRACT_CHARS as m,DEFAULT_MAX_PAPERS as f}from"../../papers/papers.js";import{rendered as w}from"../../papers/render.js";import{tool as y}from"../../tool/index.js";const i="Finds published papers on a topic and returns them as text: title, authors, venue, citation count, DOI, an open PDF when there is one, how the study was run where that is known, and the start of the abstract. Use it for what research has found or measured, and cite the DOI. Not for prices, products, news or anything from the last few months.";function b(e){const t=e.pdf??e.url??(e.doi?`https://doi.org/${e.doi}`:null);return t?{url:t,title:e.title,...e.year===null?{}:{date:String(e.year)}}:null}function x(e){return e?`${i} Papers come from ${e}.`:i}function _(e){if(typeof e?.papers!="function")throw new Error("paperSearch needs a paper searcher to run on: consensus({ apiKey }), semanticScholar() or openAlexPapers().");const{papers:t}=e,c=e.maxResults??f,u=e.maxAbstractChars??m;return y({name:"paper_search",description:x(t.source),effect:"readonly",trust:"external",wants:{name:"query",description:"the same ask as a short search phrase \u2014 the words a paper title or abstract would carry, not a sentence. A whole question finds far less."},costOf:s=>s.costMicroUsd,args:[{name:"query",type:"string",required:!0,maxLength:1e3,description:"The topic, as a phrase a paper title or abstract would contain. A whole question works and is ranked, but the shorter the phrase the better it matches."},{name:"year_min",type:"number",required:!1,min:1500,max:2200,description:"Earliest year of publication. Leave unset for any."},{name:"year_max",type:"number",required:!1,min:1500,max:2200,description:"Latest year of publication. Leave unset for any."},{name:"min_citations",type:"number",required:!1,min:0,description:"Only papers cited at least this often. Raises confidence and hides recent work."},{name:"open_access",type:"boolean",required:!1,description:"Only papers whose full text can be read without a subscription."}],run:async({query:s,year_min:p,year_max:d,min_citations:h,open_access:l})=>{const n=s.trim();if(!n)throw new Error("Name the topic to search for.");const r=await t({query:n,limit:c,yearMin:p,yearMax:d,minCitations:h,openAccess:l}),o=(r.failed??[]).map(a=>`${a.source} did not answer: ${a.reason}`);if(r.papers.length===0)throw new Error([`No papers matching "${n}" in ${r.source}.`,...o].join(" "));return{answer:[w(n,r.papers,u),...o].join(`
+
+`),results:r.papers.map(b).filter(a=>a!==null),...r.costMicroUsd===void 0?{}:{costMicroUsd:r.costMicroUsd}}}})}export{_ as paperSearch};

package/dist/builtin/polite.d.ts

@@ -0,0 +1,15 @@
+export interface PoliteOptions {
+    /** Named on every request, as the open APIs ask, so a shared IP is still identifiable. */
+    userAgent: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+    /** Injected for tests, in place of sleeping out a Retry-After. */
+    wait?: (ms: number) => Promise<void>;
+}
+/**
+ * A GET that behaves the way the free, keyless APIs ask: named, timed out,
+ * and waiting out a 429 for as long as Retry-After says before asking again.
+ */
+export declare function politeGet(opts: PoliteOptions): (url: URL) => Promise<Response>;

package/dist/builtin/polite.js

@@ -0,0 +1 @@
+const E=429,_=2,c=1e3,R=5e3,u=1e4,a=t=>new Promise(e=>setTimeout(e,t));function o(t){const e=Number(t.headers.get("retry-after")),n=Number.isFinite(e)&&e>0?e*1e3:1e3;return Math.min(n,5e3)}function A(t){const e=t.fetch??globalThis.fetch.bind(globalThis),n=t.wait??a,T=t.timeoutMs??1e4;return async i=>{for(let r=0;;r++){const s=await e(i,{signal:AbortSignal.timeout(T),headers:{"user-agent":t.userAgent,"api-user-agent":t.userAgent,...t.headers}});if(s.status!==429||r>=2)return s;await n(o(s))}}}export{A as politeGet};

package/dist/builtin/publish/index.d.ts

@@ -0,0 +1 @@
+export { type Publisher, type PublishOptions, publish } from "./publish.js";

package/dist/builtin/publish/index.js

@@ -0,0 +1 @@
+import{publish as r}from"./publish.js";export{r as publish};

package/dist/builtin/publish/publish.d.ts

@@ -0,0 +1,46 @@
+import type { PublishedFile, PublishInput, PublishTo } from "@spendgraph/sdk";
+/** The part of the spendgraph client this needs: `new Spendgraph({ apiKey }).files` satisfies it. */
+export interface Publisher {
+    publish(input: PublishInput): Promise<{
+        file: PublishedFile;
+    }>;
+}
+export interface PublishOptions {
+    /** Reaches the app with the key and the project pin; the tool never holds a credential. */
+    files: Publisher;
+    /** The project a file is filed under. A key publishes only into its own. */
+    projectId: string;
+    /** Formats this deployment will produce. Default all four. */
+    formats?: readonly PublishTo[];
+    /** Longest content accepted. Default 200000 characters. */
+    maxChars?: number;
+}
+/**
+ * Content out as a file at a public URL — markdown, a page, plain text or a
+ * PDF — so a model can hand a person something to open, not a wall of text.
+ *
+ * The app renders and stores it; this only asks. A new file every call, so it
+ * carries no effect label: a repeat is a second file, never a lost one.
+ */
+export declare function publish(opts: PublishOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "content";
+    readonly type: "text";
+    readonly required: true;
+    readonly maxLength: number;
+}, {
+    readonly name: "to";
+    readonly type: "enum";
+    readonly required: true;
+    readonly options: readonly ("pdf" | "html" | "md" | "txt")[];
+}, {
+    readonly name: "from";
+    readonly type: "enum";
+    readonly required: false;
+    readonly options: readonly ["text", "md", "html"];
+}, {
+    readonly name: "name";
+    readonly type: "string";
+    readonly required: false;
+    readonly maxLength: 120;
+    readonly description: "The file's name without its extension.";
+}]>>;

package/dist/builtin/publish/publish.js

@@ -0,0 +1 @@
+import{PUBLISH_FROM as m,PUBLISH_TO as u}from"@spendgraph/sdk";import{tool as h}from"../../tool/index.js";const l=2e5,d="md";function p(e){if(!e.files)throw new Error("publish needs the client's files resource to reach the app.");if(!e.projectId?.trim())throw new Error("publish needs the projectId a file is filed under.");const r=e.formats?.length?e.formats:u,o=e.maxChars??l;return h({name:"publish",description:`Turns content into a file people can open and returns its public URL. Formats: ${r.join(", ")}. Say what the content is written in \u2014 markdown unless told otherwise \u2014 and what to make of it. Use it when the person asked for a document, a report or a download, not for a short answer.`,args:[{name:"content",type:"text",required:!0,maxLength:o},{name:"to",type:"enum",required:!0,options:[...r]},{name:"from",type:"enum",required:!1,options:[...m]},{name:"name",type:"string",required:!1,maxLength:120,description:"The file's name without its extension."}],run:async({content:i,to:s,from:a,name:n})=>{const{file:t}=await e.files.publish({projectId:e.projectId,content:i,from:a??d,to:s,...n?{name:n}:{}});return`Published ${t.name} (${t.bytes} bytes): ${t.url}`}})}export{p as publish};

package/dist/builtin/web-search/web-search.d.ts

@@ -1,47 +1,22 @@
-/** How much searching one call is worth. */
-export type SearchDepth = "quick" | "pro" | "deep";
+import { type SearchDepth, type Searcher } from "../../search/search.js";
+export type { SearchDepth };
 export interface WebSearchOptions {
-    /** Perplexity key. Required, and read from here rather than the environment. */
-    apiKey: string;
+    /** Where answers come from: `sonar(...)`, `searxng(...)`, or your own. Required. */
+    search: Searcher;
     /**
      * Deepest tier the model may reach. Default `"pro"`.
      *
-     * `"deep"` is opt-in because `sonar-deep-research` runs for minutes and bills
+     * `"deep"` is opt-in because on Sonar it runs for minutes and bills
      * reasoning and citation tokens on top of the usual two.
      */
     maxDepth?: SearchDepth;
-    /** Hosts results are restricted to. Set here, so the model cannot widen it. */
-    domains?: string[];
-    /** Give up after this. Defaults to 60000, or 300000 on a deep search. */
-    timeoutMs?: number;
-    /** Longest answer handed back. Default 20000 characters. */
-    maxChars?: number;
-    /** Longest source list handed back. Default 20. */
-    maxResults?: number;
-    /**
-     * Tries for a rate limit or a bad minute on Perplexity's side. Default 3.
-     *
-     * A wave of sub-questions searches in parallel, so two calls landing together
-     * is ordinary and a 429 on the second is not a failure worth surfacing — it
-     * is a wait. `retry-after` is honoured where the server sends one, and the
-     * wait is spread by up to one backoff on top: a whole wave limited at the
-     * same instant computes the same delay, and retrying in step rebuilds the
-     * burst that caused it.
-     */
-    attempts?: number;
-    /** Injected for tests. */
-    fetch?: typeof fetch;
-    /** Injected for tests. */
-    sleep?: (ms: number) => Promise<void>;
-    /** Injected for tests. Returns 0 to 1, and spreads a retried wave apart. */
-    random?: () => number;
 }
 /**
- * The live web, through Perplexity's Sonar models.
+ * The live web, through the searcher it is built on.
  *
- * The tier is the model's to choose and yours to cap: `sonar-deep-research` is
- * minutes and orders of magnitude, and a model reaching for it unprompted is
- * the failure `maxDepth` exists to prevent. Tokens come back rather than a
+ * The tier is the model's to choose and yours to cap: on Sonar, deep research
+ * is minutes and orders of magnitude, and a model reaching for it unprompted
+ * is the failure `maxDepth` exists to prevent. Tokens come back rather than a
  * price, because what a search costs is the pricing table's business.
  */
 export declare function webSearch(opts: WebSearchOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
@@ -55,7 +30,7 @@ export declare function webSearch(opts: WebSearchOptions): import("../../index.j
     readonly type: "enum";
     readonly required: false;
     readonly options: readonly ["quick", "pro", "deep"];
-    readonly description: "Default quick. Raise it only when a first pass would not settle it.";
+    readonly description: string;
 }, {
     readonly name: "recency";
     readonly type: "enum";

package/dist/builtin/web-search/web-search.js

@@ -1 +1 @@
-import{tool as w}from"../../tool/index.js";import{readReply as y}from"./reply.js";const l=["quick","pro","deep"],_={quick:"sonar",pro:"sonar-pro",deep:"sonar-deep-research"},g="https://api.perplexity.ai/chat/completions",b=6e4,E=3e5,S=2e4,x=20,A=500,M=500,T=8e3;function k(e){const t=e.headers.get("retry-after");if(!t)return null;const n=Number(t);return Number.isFinite(n)&&n>=0?n*1e3:null}const O=e=>e===429||e>=500;function q(e,t){return"Searches the live web and returns an answer with the sources it rests on. Use it for anything that turns on current facts \u2014 prices, releases, who holds a post, what changed. quick is one pass and is right for most lookups; pro searches wider and cites more."+(e==="deep"?" deep is an exhaustive multi-step review: minutes, and many times the cost. Ask for it only when a wrong answer is expensive.":" deep is not enabled here.")+(t?.length?` Results come only from ${t.join(", ")}.`:"")}function F(e){if(!e.apiKey?.trim())throw new Error("webSearch needs a Perplexity apiKey; it will not read one from the process.");const t=e.fetch??globalThis.fetch.bind(globalThis),n=e.maxDepth??"pro",d=Math.max(1,e.attempts??3),u=e.sleep??(o=>new Promise(r=>setTimeout(r,o)));return w({name:"web_search",description:q(n,e.domains),effect:"readonly",args:[{name:"query",type:"string",required:!0,maxLength:1e3,description:"What to find out, as a question. One thing, not several."},{name:"depth",type:"enum",required:!1,options:["quick","pro","deep"],description:"Default quick. Raise it only when a first pass would not settle it."},{name:"recency",type:"enum",required:!1,options:["day","week","month","year"],description:"Only consider pages published within this. Leave unset for anything."}],run:async({query:o,depth:r="quick",recency:c})=>{if(l.indexOf(r)>l.indexOf(n))throw new Error(`web_search was asked for "${r}", above the "${n}" this deployment allows.`);const a=_[r],m=r==="deep"?E:b;for(let i=1;;i++){const s=await t(g,{method:"POST",signal:AbortSignal.timeout(e.timeoutMs??m),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({model:a,messages:[{role:"user",content:o}],...c?{search_recency_filter:c}:{},...e.domains?.length?{search_domain_filter:e.domains}:{}})});if(s.ok)return y(await s.json(),a,e.maxChars??S,e.maxResults??x);const p=(await s.text()).slice(0,A);if(!O(s.status)||i===d)throw new Error(`Perplexity returned ${s.status} for ${a}: ${p}`);const h=Math.min(T,M*2**(i-1)),f=k(s)??h;await u(f+h*(e.random??Math.random)())}}})}export{F as webSearch};
+import{DEPTHS as t}from"../../search/search.js";import{tool as h}from"../../tool/index.js";const s="Searches the live web and returns what it found with the sources it rests on. Use it for anything that turns on current facts \u2014 laws, regulations, standards, prices, releases, dates, versions, who holds a post, what changed \u2014 and never answer those from memory. Given a link, reads that page.";function u(e){return e?.length?`${s} Results come only from ${e.join(", ")}; anything elsewhere is out of reach.`:s}function c(e){return e==="deep"?"Default quick, one pass, right for most lookups. pro searches wider. deep is an exhaustive review: minutes, and many times the cost; ask for it only when a wrong answer is expensive.":"Default quick, one pass, right for most lookups. Raise to pro when a first pass would not settle it. deep is not enabled here."}function f(e){if(typeof e?.search!="function")throw new Error("webSearch needs a searcher to run on: sonar({ apiKey }) or searxng({ baseUrl }).");const{search:o}=e,r=e.maxDepth??"pro";return h({name:"web_search",description:u(e.search.domains),effect:"readonly",trust:"external",args:[{name:"query",type:"string",required:!0,maxLength:1e3,description:"What to find out, as a question. One thing, not several."},{name:"depth",type:"enum",required:!1,options:["quick","pro","deep"],description:c(r)},{name:"recency",type:"enum",required:!1,options:["day","week","month","year"],description:"Only consider pages published within this. Leave unset for anything."}],run:async({query:a,depth:n="quick",recency:i})=>{if(t.indexOf(n)>t.indexOf(r))throw new Error(`web_search was asked for "${n}", above the "${r}" this deployment allows.`);return o({query:a,depth:n,recency:i})}})}export{f as webSearch};

package/dist/builtin/wikidata/api.d.ts

@@ -0,0 +1,40 @@
+import { type PoliteOptions } from "../polite.js";
+export interface Found {
+    id: string;
+    label: string;
+    description: string;
+}
+export interface Snak {
+    snaktype: string;
+    datatype?: string;
+    datavalue?: {
+        type: string;
+        value: unknown;
+    };
+}
+export interface Statement {
+    mainsnak: Snak;
+    rank: "preferred" | "normal" | "deprecated";
+    references?: {
+        snaks?: Record<string, Snak[]>;
+    }[];
+}
+export interface Entity {
+    id: string;
+    label: string;
+    description: string;
+    claims: Record<string, Statement[]>;
+    /** The Wikipedia article in the tool's language, when there is one. */
+    wikipedia: string | null;
+}
+export declare const ITEM_URL = "https://www.wikidata.org/wiki/";
+export interface WikidataApi {
+    search(name: string): Promise<Found | null>;
+    entity(id: string): Promise<Entity | null>;
+    labels(ids: readonly string[]): Promise<Map<string, string>>;
+}
+export interface ApiOptions extends Omit<PoliteOptions, "userAgent"> {
+    language?: string;
+}
+/** The three Wikidata calls the tool makes, behind one interface a test can fake. */
+export declare function wikidataApi(opts?: ApiOptions): WikidataApi;

package/dist/builtin/wikidata/api.js

@@ -0,0 +1 @@
+import{politeGet as u}from"../polite.js";const d="https://www.wikidata.org/w/api.php",f="spendgraph-tools (https://spendgraph.locusgraph.com)",g=50,y="https://www.wikidata.org/wiki/";function h(i,s){const e=i.sitelinks?.[`${s}wiki`]?.title;return e?`https://${s}.wikipedia.org/wiki/${encodeURIComponent(e.replace(/ /g,"_"))}`:null}function l(i,s){return i?.[s]?.value??""}function k(i,s){const e=[];for(let o=0;o<i.length;o+=s)e.push(i.slice(o,o+s));return e}function m(i={}){const s=u({...i,userAgent:f}),e=i.language??"en",o=async n=>{const a=new URL(d);for(const[r,c]of Object.entries({...n,format:"json"}))a.searchParams.set(r,c);const t=await s(a);if(!t.ok)throw new Error(`Wikidata answered ${t.status} to ${n.action}.`);return await t.json()};return{async search(n){const t=(await o({action:"wbsearchentities",search:n,language:e,limit:"1"})).search?.[0];return t?{id:t.id,label:t.label??t.id,description:t.description??""}:null},async entity(n){const t=(await o({action:"wbgetentities",ids:n,props:"claims|labels|descriptions|sitelinks",languages:e,sitefilter:`${e}wiki`})).entities?.[n];return!t||t.missing!==void 0?null:{id:n,label:l(t.labels,e)||n,description:l(t.descriptions,e),claims:t.claims??{},wikipedia:h(t,e)}},async labels(n){const a=new Map;for(const t of k([...new Set(n)],g)){const r=await o({action:"wbgetentities",ids:t.join("|"),props:"labels",languages:e});for(const[c,w]of Object.entries(r.entities??{})){const p=l(w.labels,e);p&&a.set(c,p)}}return a}}}export{y as ITEM_URL,m as wikidataApi};

package/dist/builtin/wikidata/index.d.ts

@@ -0,0 +1,5 @@
+export type { ApiOptions, Entity, Found, Statement, WikidataApi } from "./api.js";
+export { wikidataApi } from "./api.js";
+export type { Fact } from "./render.js";
+export { factsOf, rendered, statementsOf } from "./render.js";
+export { type WikidataOptions, wikidata } from "./wikidata.js";

package/dist/builtin/wikidata/index.js

@@ -0,0 +1 @@
+import{wikidataApi as r}from"./api.js";import{factsOf as f,rendered as o,statementsOf as i}from"./render.js";import{wikidata as m}from"./wikidata.js";export{f as factsOf,o as rendered,i as statementsOf,m as wikidata,r as wikidataApi};

package/dist/builtin/wikidata/render.d.ts

@@ -0,0 +1,13 @@
+import { type Entity, type Snak, type Statement } from "./api.js";
+export interface Fact {
+    property: string;
+    values: string[];
+    /** Reference URLs the statements cite, where the value can be checked. */
+    sources: string[];
+}
+/** Entity ids a snak refers to — its value, or the unit of a quantity — for one labels call. */
+export declare function referenced(snak: Snak): string[];
+/** The statements worth reading, in the order Wikidata lists them, deprecated ones dropped. */
+export declare function statementsOf(entity: Entity): [string, Statement[]][];
+export declare function factsOf(statements: readonly [string, Statement[]][], labels: ReadonlyMap<string, string>): Fact[];
+export declare function rendered(entity: Entity, facts: readonly Fact[]): string;

package/dist/builtin/wikidata/render.js

@@ -0,0 +1,2 @@
+import{ITEM_URL as c}from"./api.js";const l=new Set(["wikibase-item","time","quantity","string","monolingualtext","url","globe-coordinate"]),d=9,p=10,f=11,s="http://www.wikidata.org/entity/",$="P854";function g(t){return(t.references??[]).flatMap(n=>(n.snaks?.[$]??[]).flatMap(r=>{const e=r.datavalue?.value;return typeof e=="string"?[e]:[]}))}function m(t){const n=t.filter(e=>e.rank!=="deprecated"),r=n.filter(e=>e.rank==="preferred");return r.length>0?r:n}function h(t){return t.snaktype==="value"&&l.has(t.datatype??"")&&t.datavalue!==void 0}function w(t){const n=t.time.replace(/^\+/,""),[r]=n.split("T"),[e="",i="",o=""]=(r??"").split("-");return t.precision>=f?`${e}-${i}-${o}`:t.precision===p?`${e}-${i}`:t.precision===d?e:`c. ${e}`}function u(t){const n=t?.id;return typeof n=="string"?n:null}function y(t){const n=t.datavalue?.value,r=u(n),e=n?.unit?.startsWith(s)?n.unit.slice(s.length):null;return[r,e].filter(i=>i!==null)}function v(t,n){const r=t.datavalue?.value;switch(t.datatype){case"wikibase-item":{const e=u(r);return e?n.get(e)??e:null}case"time":return w(r);case"quantity":{const{amount:e,unit:i}=r,o=i.startsWith(s)?i.slice(s.length):null,a=o?n.get(o)??o:"";return`${e.replace(/^\+/,"")}${a?` ${a}`:""}`}case"monolingualtext":return r.text;case"globe-coordinate":{const{latitude:e,longitude:i}=r;return`${e}, ${i}`}default:return typeof r=="string"?r:null}}function x(t){return Object.entries(t.claims).map(([n,r])=>[n,m(r).filter(e=>h(e.mainsnak))]).filter(([,n])=>n.length>0)}function M(t,n){return t.map(([r,e])=>({property:n.get(r)??r,values:e.flatMap(i=>{const o=v(i.mainsnak,n);return o?[o]:[]}),sources:[...new Set(e.flatMap(g))]}))}function k(t){const n=t.sources.length>0?` \u2014 source: ${t.sources.join(", ")}`:"";return`${t.property}: ${t.values.join(", ")}${n}`}function R(t,n){const r=`${t.label} (${t.id})${t.description?` \u2014 ${t.description}`:""}`,e=[`${c}${t.id}`,...t.wikipedia?[t.wikipedia]:[]];return[r,...n.map(k),`source: ${e.join(" \xB7 ")}`].join(`
+`)}export{M as factsOf,y as referenced,R as rendered,x as statementsOf};

package/dist/builtin/wikidata/wikidata.d.ts

@@ -0,0 +1,23 @@
+import { type ApiOptions, type WikidataApi } from "./api.js";
+import { type Fact } from "./render.js";
+export interface WikidataOptions extends ApiOptions {
+    /** Facts kept per thing. Default 30; a country has hundreds. */
+    maxFacts?: number;
+    /** Injected for tests, in place of the three calls to Wikidata. */
+    api?: WikidataApi;
+}
+export declare function matching(facts: readonly Fact[], about: string): Fact[];
+/**
+ * Facts about a thing from Wikidata, as text — its label, what it is, and
+ * the statements made about it, with every id resolved to a name.
+ *
+ * Free and unauthenticated. Entity, date, number and place claims are what it
+ * settles; prices, versions and anything recent are not in it.
+ */
+export declare function wikidata(opts?: WikidataOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 200;
+    readonly description: string;
+}]>>;

package/dist/builtin/wikidata/wikidata.js

@@ -0,0 +1 @@
+import{tool as y}from"../../tool/index.js";import{wikidataApi as b}from"./api.js";import{factsOf as g,referenced as k,rendered as p,statementsOf as x}from"./render.js";const v=30;function A(e){const t=e.indexOf(":");if(t<1)return{name:e.trim(),about:null};const o=e.slice(t+1).trim();return{name:e.slice(0,t).trim(),about:o||null}}const L={founded:["inception","start time"],founder:["founded by"],created:["inception"],started:["inception"],began:["inception"],born:["date of birth"],died:["date of death"],headquarters:["headquarters location"],ceo:["chief executive officer"],boss:["chief executive officer"],owner:["owned by"],parent:["parent organization"]};function N(e,t){const s=t.toLowerCase().split(/\s+/).filter(Boolean).flatMap(n=>[n,...L[n]??[]]);return e.filter(n=>{const a=n.property.toLowerCase();return s.some(r=>a.includes(r))})}function F(e={}){const t=e.api??b(e),o=e.maxFacts??v;return y({name:"wikidata",effect:"readonly",trust:"external",description:"One curated fact about one named thing, with the source it came from. It settles who, when, where and what-is: who makes or runs something, when it began or a person was born, what a place's capital or population is, what a compound's formula is. Name the thing \u2014 a company, person, place, product, substance or work \u2014 and add ': ' and the one property wanted, as in 'Cloudflare: inception' or 'Ozempic: manufacturer'. Not for what a study found, which is a paper and not a property; not for a price or anything contested, which has no single recorded value; and not for anything recent, because a volunteer updates it when they get round to it.",wants:{name:"entity",description:"the thing's name on its own \u2014 'Novo Nordisk', never a sentence or a question \u2014 optionally followed by ': ' and the one property wanted, as in 'Novo Nordisk: inception'."},args:[{name:"question",type:"string",required:!0,maxLength:200,description:"The thing's name on its own, optionally followed by ': ' and the property wanted. A question finds nothing \u2014 Wikidata is searched by name."}],run:async({question:s})=>{const{name:n,about:a}=A(s);if(!n)throw new Error("Name the thing to look up.");const r=await t.search(n);if(!r)throw new Error(`Wikidata has nothing named "${n}".`);const i=await t.entity(r.id);if(!i)throw new Error(`Wikidata has no record for ${r.id}.`);const c=x(i),f=c.flatMap(([l,w])=>[l,...w.flatMap(m=>k(m.mainsnak))]),u=await t.labels(f),d=g(c,u);if(!a)return p(i,d.slice(0,o));const h=N(d,a);if(h.length===0)throw new Error(`Wikidata records nothing about "${a}" for ${i.label}.`);return p(i,h.slice(0,o))}})}export{N as matching,F as wikidata};

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 +1 @@
-import{toAnthropic as w,toMarkdown as d,toOpenAI as g}from"../wire/index.js";import{invokeTool as O}from"./invoke.js";import{warnOnOverlap as h}from"./overlap.js";import{scorerFor as k}from"./score.js";import{selectTools as b}from"./select.js";import{toStep as T}from"./step.js";import{ceilingFor as l}from"./terms.js";import{newTrace as M}from"./trace.js";function I(c,a={}){const f=a.now??(()=>Date.now()),m=l(a.limit,6),t=new Map;for(const e of c){if(t.has(e.name))throw new Error(`Two tools are called "${e.name}".`);t.set(e.name,e)}const n=new Map;(a.warnOnOverlap??!0)&&h([...t.values()]);const p=k([...t.values()]),s=e=>({name:e.name,description:e.description,args:e.args,...e.aliases?.length?{aliases:e.aliases}:{},...e.effect?{effect:e.effect}:{}}),r=()=>[...t.values()].map(s),i={all:()=>[...t.values()],missing:e=>e.filter(o=>!t.has(o)),get:e=>t.get(e),effectOf:e=>t.get(e)?.effect,destructive:()=>[...t.values()].filter(e=>e.effect==="destructive").map(e=>e.name),unannotated:()=>[...t.values()].filter(e=>e.effect===void 0).map(e=>e.name),declarations:e=>e?e.map(o=>t.get(o)).filter(Boolean).map(o=>s(o)):r(),anthropic:e=>w(e??r()),openai:e=>g(e??r()),markdown:(e,o)=>d(e??r(),o),select:(e="",o)=>b([...t.values()],n,s,p,e,l(o,m)),invoke:(e,o)=>O(t,n,f,e,o),usage:()=>Object.fromEntries(n),step:(e,o)=>T(e,o),trace:(e="",o)=>M(i.select(e,o),(u,v)=>i.invoke(u,v))};return i}export{I as toolbus};
+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

@@ -1,8 +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 declare function busgroup(members: BusMember[], opts?: ToolBusOptions): 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

@@ -1 +1 @@
-import{toAnthropic as O,toMarkdown as I,toOpenAI as $}from"../wire/index.js";import{scorerFor as k}from"./score.js";import{toStep as A}from"./step.js";import{ceilingFor as M,termsIn as T}from"./terms.js";import{newTrace as x}from"./trace.js";const B=6,v=3;function D(t){return{name:t.name,description:t.description,args:[]}}function F(t){const s=new Map;for(const e of t)for(const o of e.bus.all()){const c=s.get(o.name);if(c)throw new Error(`Two buses offer a tool called "${o.name}": "${c.name}" and "${e.name}". A name has to say which one runs.`);s.set(o.name,e)}return s}function S(t){return t.flatMap(s=>{const e=s.bus.all().filter(o=>o.pinned).map(o=>o.name);return e.length>0?s.bus.declarations(e):[]})}function C(t){const s=[],e=new Set;let o=t;return{chosen:s,holds:c=>e.has(c),full:()=>s.length>=o,room:()=>t-s.length,narrowTo:c=>{o=Math.min(o,c)},take(c){e.has(c.name)||s.length>=o||(e.add(c.name),s.push(c))}}}function L(t,s,e){const o=t.flat(),c=k(o),f=o.map(l=>({declaration:l,n:c(l,s)})).sort((l,u)=>u.n-l.n);if(f.length===0||f[0].n===0)return!1;f.length>1&&f[0].n>=f[1].n*2&&e.narrowTo(e.chosen.length+v);for(const{declaration:l}of f){if(e.full())break;e.take(l)}return!0}function N(t,s){for(let e=0;!s.full();e++){let o=!1;for(const c of t){const f=c[e];if(f!==void 0&&(o=!0,s.take(f),s.full()))break}if(!o)break}}function z(t,s={}){const e=new Set;for(const n of t){if(e.has(n.name))throw new Error(`Two buses are called "${n.name}".`);e.add(n.name)}const o=F(t),c=S(t),f=new Map(t.map(n=>[n,D(n)])),m=k([...f.values()]),l=M(s.limit,B),u=n=>o.get(n),b=()=>t.flatMap(n=>n.bus.all()),p=()=>t.flatMap(n=>n.bus.declarations()),y=n=>t.map(a=>({member:a,n:m(f.get(a),n)})).sort((a,r)=>r.n-a.n),g={all:b,missing:n=>n.filter(a=>!o.has(a)),get:n=>u(n)?.bus.get(n),effectOf:n=>u(n)?.bus.effectOf(n),destructive:()=>t.flatMap(n=>n.bus.destructive()),unannotated:()=>t.flatMap(n=>n.bus.unannotated()),declarations:n=>n?t.flatMap(a=>{const r=n.filter(i=>o.get(i)===a);return r.length>0?a.bus.declarations(r):[]}):p(),anthropic:n=>O(n??p()),openai:n=>$(n??p()),markdown:(n,a)=>I(n??p(),a),select:(n="",a)=>{const r=C(M(a,l));for(const h of c)r.take(h);const i=r.room();if(i<=0)return r.chosen;const d=y(T(n)),w=d.map(({member:h})=>h.bus.select(n,i).filter(E=>!r.holds(E.name)));if(d.length>1&&d[0].n>0&&d[0].n>=d[1].n*2&&w[0].length>0){r.narrowTo(r.chosen.length+v);for(const h of w[0])r.take(h);return r.chosen}return L(w,T(n),r)||N(w,r),r.chosen},invoke:async(n,a)=>{const r=u(n);return r?r.bus.invoke(n,a):{name:n,args:a,status:"failed",output:"",error:`No tool called "${n}". Offered: ${[...o.keys()].join(", ")}`,latencyMs:0}},usage:()=>Object.assign({},...t.map(n=>n.bus.usage())),step:(n,a)=>A(n,a),trace:(n="",a)=>x(g.select(n,a),(r,i)=>g.invoke(r,i))};return g}export{z as busgroup};
+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,4 +1,7 @@
 export { type ToolBus, toolbus } from "./bus.js";
-export { type BusMember, busgroup } from "./group.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 +1 @@
-import{toolbus as e}from"./bus.js";import{busgroup as t}from"./group.js";import{newTrace as m}from"./trace.js";export{t as busgroup,m as newTrace,e as toolbus};
+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 +1,3 @@
-import{FieldValidationError as d,validateFields as f}from"@spendgraph/sdk";import{readyArgs as p}from"./args.js";import{reasonFor as y,render as g}from"./output.js";async function F(n,i,r,t,s){const a=r(),e=n.get(t),o={name:t,args:s,latencyMs:0};if(!e)return{...o,status:"failed",output:"",error:`No tool called "${t}". Offered: ${[...n.keys()].join(", ")}`};const l=f(s,e.args);if(l.length>0)return{...o,status:"failed",output:"",error:new d(l).message,latencyMs:r()-a};i.set(t,(i.get(t)??0)+1);const c=p(e.args,s);try{const u=await e.run(c);return{...o,status:"completed",output:g(u),latencyMs:r()-a}}catch(u){return{...o,status:"failed",output:"",error:y(u),latencyMs:r()-a}}}export{F as invokeTool};
+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};