@spendgraph/tools 0.6.0 → 0.7.0

package/dist/builtin/http/retry-after.d.ts

@@ -0,0 +1,14 @@
+/**
+ * How long a server asked you to wait, in milliseconds, or null.
+ *
+ * `Retry-After` is the one part of a 429 or a 503 that is not guesswork: the
+ * server knows when its window resets and says so. Dropping it leaves a caller
+ * backing off by a schedule it invented, which is either too slow or — the
+ * expensive one — too fast, and a retry inside the window spends a request to
+ * be told to wait again.
+ *
+ * Two forms, both in the spec: whole seconds, or an HTTP date. A date in the
+ * past is zero rather than negative, because "wait -4 seconds" is not something
+ * a caller should have to guard against.
+ */
+export declare function retryAfterMs(header: string | null, now?: () => number): number | null;

package/dist/builtin/http/retry-after.js

@@ -0,0 +1 @@
+function u(r,n=Date.now){if(!r)return null;const t=r.trim();if(/^\d+$/.test(t))return Number(t)*1e3;const e=Date.parse(t);return Number.isNaN(e)?null:Math.max(0,e-n())}export{u as retryAfterMs};

package/dist/builtin/index.d.ts

@@ -1,12 +1,16 @@
 export { calculate, evaluate } from "./calculate/index.js";
 export { type ClockOptions, currentTime } from "./clock/index.js";
 export { type CodeExecOptions, codeExec, type Sandbox, type SandboxRequest, type SandboxResult, } from "./code-exec/index.js";
-export { dateMath } from "./date/index.js";
-export { type DeepRecallOptions, deepRecall, type RecalledFact, type Recaller, type RecallResult, } from "./deep-recall/index.js";
-export { type EscalateOptions, type EscalationRequest, escalate } from "./escalate/index.js";
+export { dateMath, dates } from "./date/index.js";
+export { type Declined, decline, declinedFor, isDeclined, type Unanswerable, } from "./decline/index.js";
+export { type Escalated, type EscalateOptions, type EscalationRequest, escalate, escalationOf, isEscalated, } from "./escalate/index.js";
+export { type ExtractOptions, extract } from "./extract/index.js";
 export { answerOf, type Finished, finish, isFinished } from "./finish/index.js";
-export { checkUrl, type HttpOptions, httpRequest } from "./http/index.js";
-export { type JsonQueryOptions, jsonQuery } from "./json/index.js";
+export { checkUrl, type HttpOptions, httpRequest, retryAfterMs } from "./http/index.js";
+export { type JsonQueryOptions, jsonFrom, jsonQuery } from "./json/index.js";
+export { type NotesOptions, type NotesStore, notes, notesStore } from "./notes/index.js";
+export { type OpenAlexApi, type OpenAlexOptions, openalex } from "./openalex/index.js";
+export { type Publisher, type PublishOptions, publish } from "./publish/index.js";
 export { think } from "./think/index.js";
 export { type SearchDepth, type WebSearchOptions, webSearch } from "./web-search/index.js";
-export { type ArtifactFormat, CommissionAbortedError, type CommissionClient, CommissionTimeoutError, DEFAULT_DESIGN, type DesignGuide, mergeDesign, renderDesign, type WriteDocumentOptions, writeDocument, } from "./write-document/index.js";
+export { type WikidataApi, type WikidataOptions, wikidata } from "./wikidata/index.js";

package/dist/builtin/index.js

@@ -1 +1 @@
-import{calculate as o,evaluate as t}from"./calculate/index.js";import{currentTime as i}from"./clock/index.js";import{codeExec as p}from"./code-exec/index.js";import{dateMath as x}from"./date/index.js";import{deepRecall as a}from"./deep-recall/index.js";import{escalate as h}from"./escalate/index.js";import{answerOf as u,finish as d,isFinished as D}from"./finish/index.js";import{checkUrl as g,httpRequest as w}from"./http/index.js";import{jsonQuery as b}from"./json/index.js";import{think as A}from"./think/index.js";import{webSearch as F}from"./web-search/index.js";import{CommissionAbortedError as S,CommissionTimeoutError as U,DEFAULT_DESIGN as j,mergeDesign as q,renderDesign as v,writeDocument as y}from"./write-document/index.js";export{S as CommissionAbortedError,U as CommissionTimeoutError,j as DEFAULT_DESIGN,u as answerOf,o as calculate,g as checkUrl,p as codeExec,i as currentTime,x as dateMath,a as deepRecall,h as escalate,t as evaluate,d as finish,w as httpRequest,D as isFinished,b as jsonQuery,q as mergeDesign,v as renderDesign,A as think,F as webSearch,y as writeDocument};
+import{calculate as o,evaluate as t}from"./calculate/index.js";import{currentTime as a}from"./clock/index.js";import{codeExec as x}from"./code-exec/index.js";import{dateMath as s,dates as i}from"./date/index.js";import{decline as n,declinedFor as l,isDeclined as d}from"./decline/index.js";import{escalate as u,escalationOf as k,isEscalated as w}from"./escalate/index.js";import{extract as b}from"./extract/index.js";import{answerOf as y,finish as E,isFinished as M}from"./finish/index.js";import{checkUrl as S,httpRequest as q,retryAfterMs as v}from"./http/index.js";import{jsonFrom as D,jsonQuery as Q}from"./json/index.js";import{notes as T,notesStore as U}from"./notes/index.js";import{openalex as z}from"./openalex/index.js";import{publish as C}from"./publish/index.js";import{think as H}from"./think/index.js";import{webSearch as J}from"./web-search/index.js";import{wikidata as L}from"./wikidata/index.js";export{y as answerOf,o as calculate,S as checkUrl,x as codeExec,a as currentTime,s as dateMath,i as dates,n as decline,l as declinedFor,u as escalate,k as escalationOf,t as evaluate,b as extract,E as finish,q as httpRequest,d as isDeclined,w as isEscalated,M as isFinished,D as jsonFrom,Q as jsonQuery,T as notes,U as notesStore,z as openalex,C as publish,v as retryAfterMs,H as think,J as webSearch,L as wikidata};

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

@@ -1,2 +1,3 @@
 export { type JsonQueryOptions, jsonQuery } from "./json.js";
+export { jsonFrom } from "./parse.js";
 export { readPath } from "./path.js";

package/dist/builtin/json/index.js

@@ -1 +1 @@
-import{jsonQuery as e}from"./json.js";import{readPath as a}from"./path.js";export{e as jsonQuery,a as readPath};
+import{jsonQuery as e}from"./json.js";import{jsonFrom as t}from"./parse.js";import{readPath as p}from"./path.js";export{t as jsonFrom,e as jsonQuery,p as readPath};

package/dist/builtin/json/json.js

@@ -1 +1 @@
-import{tool as i}from"../../tool/index.js";import{readPath as l}from"./path.js";const d=2e4;function f(a={}){const e=a.maxChars??d;return i({name:"json_query",effect:"readonly",description:"Reads one value out of a JSON document by path. Paths look like `invoices[0].total`, or `invoices[*].total` for every element. Use it instead of reading a long document yourself.",args:[{name:"json",type:"text",required:!0,maxLength:2e5},{name:"path",type:"string",required:!0,maxLength:500}],run:({json:s,path:t})=>{let o;try{o=JSON.parse(s)}catch(u){throw new Error(`json is not valid JSON: ${u.message}`)}const n=l(o,t);if(n===void 0)return{found:!1,path:t,value:null};const r=JSON.stringify(n)??"null";return{found:!0,path:t,value:n,truncated:r.length>e,...r.length>e?{value:`${r.slice(0,e)}\u2026`}:{}}}})}export{f as jsonQuery};
+import{tool as s}from"../../tool/index.js";import{jsonFrom as i}from"./parse.js";import{readPath as l}from"./path.js";const d=2e4;function g(r={}){const e=r.maxChars??d;return s({name:"json_query",effect:"readonly",description:"Reads one value out of a JSON document by path. Paths look like `invoices[0].total`, or `invoices[*].total` for every element. Use it instead of reading a long document yourself.",args:[{name:"json",type:"text",required:!0,maxLength:2e5},{name:"path",type:"string",required:!0,maxLength:500}],run:({json:a,path:n})=>{const u=i(a),t=l(u,n);if(t===void 0)return{found:!1,path:n,value:null};const o=JSON.stringify(t)??"null";return{found:!0,path:n,value:t,truncated:o.length>e,...o.length>e?{value:`${o.slice(0,e)}\u2026`}:{}}}})}export{g as jsonQuery};

package/dist/builtin/json/parse.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The JSON inside a model's reply, whatever it wrapped it in.
+ *
+ * The two commonest structured-output failures are not bad JSON at all: a
+ * fenced block, and a sentence before or after it. Both parse perfectly once
+ * the payload is found, and every caller otherwise writes the same fence
+ * stripping by hand and gets the second case wrong.
+ *
+ * It finds the JSON; it never rewrites it. A trailing comma, a single-quoted
+ * key or a missing brace stays an error, because repairing those is guessing at
+ * what was meant and a wrong guess is a confidently wrong record. Those belong
+ * in a bounded repair round, where the model is told what failed and answers
+ * again.
+ */
+export declare function jsonFrom(text: string): unknown;

package/dist/builtin/json/parse.js

@@ -0,0 +1 @@
+const l=/```(?:[a-zA-Z0-9_-]+)?\s*\n?([\s\S]*?)```/,f={"{":"}","[":"]"};function a(e){const n=e.search(/[[{]/);if(n===-1)return null;const t=f[e[n]];let o=0,i=!1,s=!1;for(let r=n;r<e.length;r+=1){const c=e[r];if(s){s=!1;continue}if(c==="\\"&&i){s=!0;continue}if(c==='"'){i=!i;continue}if(!i){if(c===e[n])o+=1;else if(c===t&&(o-=1,o===0))return e.slice(n,r+1)}}return null}function u(e){const n=e.trim();for(const t of[n,l.exec(n)?.[1]?.trim(),a(n)])if(t)try{return JSON.parse(t)}catch{}throw new Error(`No JSON in ${n.length>80?`${n.slice(0,80)}\u2026`:n||"an empty reply"}`)}export{u as jsonFrom};

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

@@ -0,0 +1 @@
+export { ACTIONS, type NotesOptions, type NotesStore, notes, notesStore } from "./notes.js";

package/dist/builtin/notes/index.js

@@ -0,0 +1 @@
+import{ACTIONS as t,notes as r,notesStore as n}from"./notes.js";export{t as ACTIONS,r as notes,n as notesStore};

package/dist/builtin/notes/notes.d.ts

@@ -0,0 +1,45 @@
+/** Boards by session, one per process unless you hand every bus the same one. */
+export type NotesStore = Map<string, string[]>;
+export interface NotesOptions {
+    /** Whose board: a session id, so a follow-up question sees what the last run worked out. */
+    session: string;
+    /** Where boards live. Default one store for the process; pass your own to share or to inspect. */
+    store?: NotesStore;
+    /** Notes a board holds before `post` is refused. Default 50. */
+    maxNotes?: number;
+}
+export declare const ACTIONS: readonly ["post", "read", "replace", "clear"];
+export declare function notesStore(): NotesStore;
+/**
+ * A board the model writes to and reads back during a session — what it is
+ * doing, what is still missing, what it decided — kept in memory and gone when
+ * the process is.
+ *
+ * `think` is write-once and never seen again; this is the model's own chosen
+ * state, readable three steps later. It is not memory: a note worth keeping
+ * goes to `remember`, on purpose, so half-thoughts never surface as facts.
+ *
+ * `replace` is what makes it usable as a running plan. Append-only, a plan
+ * re-posted each turn becomes twenty notes where the twentieth contradicts the
+ * third and `read` shows both — and the only way back is `clear`, which throws
+ * the plan away with the noise. One note, rewritten, is the whole pattern.
+ *
+ * No effect label: `read` changes nothing and `post` changes only this board.
+ */
+export declare function notes(opts: NotesOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "action";
+    readonly type: "enum";
+    readonly required: true;
+    readonly options: readonly ["post", "read", "replace", "clear"];
+}, {
+    readonly name: "note";
+    readonly type: "text";
+    readonly required: false;
+    readonly maxLength: 2000;
+}, {
+    readonly name: "number";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 1;
+    readonly description: "Which note to replace, as `read` numbers them.";
+}]>>;

package/dist/builtin/notes/notes.js

@@ -0,0 +1,2 @@
+import{tool as d}from"../../tool/index.js";const l=["post","read","replace","clear"],u=50,c=2e3,w=new Map;function p(){return new Map}function m(e){return e.map((t,n)=>`#${n+1} ${t}`).join(`
+`)}function f(e,t,n){if(t===void 0)throw new Error("replace needs the `number` of the note.");if(e.length===0)throw new Error("There is nothing on the board to replace.");if(t<1||t>e.length)throw new Error(`There is no note #${t}; the board holds #1 to #${e.length}.`);const o=[...e];return o[t-1]=n,o}function y(e){if(!e.session?.trim())throw new Error("notes needs the session whose board this is.");const t=e.store??w,n=e.maxNotes??u,o=()=>t.get(e.session)??[];return d({name:"notes",description:"Your notes for this session. `post` writes one \u2014 what you are doing, what is still missing, what you decided. `read` shows them all, numbered, in order. `replace` rewrites one by its number \u2014 keep a plan as a single note and rewrite it as you go, rather than posting its status again each turn. `clear` wipes them. They last the session and nobody else reads them; use `remember` for anything that should outlast it.",args:[{name:"action",type:"enum",required:!0,options:[...l]},{name:"note",type:"text",required:!1,maxLength:c},{name:"number",type:"number",required:!1,min:1,description:"Which note to replace, as `read` numbers them."}],run:({action:s,note:h,number:a})=>{const r=o();if(s==="read")return r.length?m(r):"Nothing on the board yet.";if(s==="clear")return t.delete(e.session),`Cleared ${r.length} note${r.length===1?"":"s"}.`;const i=h?.trim();if(!i)throw new Error(`${s} needs a \`note\`.`);if(s==="replace")return t.set(e.session,f(r,a,i)),`#${a} rewritten.`;if(r.length>=n)throw new Error(`The board holds ${n} notes; clear it, or say less.`);return t.set(e.session,[...r,i]),`#${r.length+1} noted.`}})}export{l as ACTIONS,y as notes,p as notesStore};

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

@@ -0,0 +1,22 @@
+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 OpenAlexApi {
+    search(query: string, limit: number): Promise<Paper[]>;
+}
+export interface ApiOptions extends Omit<PoliteOptions, "userAgent"> {
+    /** Your address, sent as `mailto`; OpenAlex answers named callers from a faster pool. */
+    mailto?: 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{politeGet as n}from"../polite.js";const i="https://api.openalex.org/works",c="spendgraph-tools (https://spendgraph.locusgraph.com)",l=["id","doi","title","publication_year","cited_by_count","authorships","primary_location","open_access","abstract_inverted_index"].join(",");function p(t){if(!t)return"";const e=[];for(const[o,s]of Object.entries(t))for(const r of s)e[r]=o;return e.filter(o=>o!==void 0).join(" ")}function u(t){return{title:t.title?.trim()||"(untitled)",year:t.publication_year??null,authors:(t.authorships??[]).flatMap(e=>e.author?.display_name?[e.author.display_name]:[]),venue:t.primary_location?.source?.display_name??null,citations:t.cited_by_count??0,doi:t.doi?.replace(/^https?:\/\/doi\.org\//,"")??null,pdf:t.open_access?.oa_url??t.primary_location?.pdf_url??null,abstract:p(t.abstract_inverted_index)}}function h(t={}){const e=n({...t,userAgent:c});return{async search(o,s){const r=new URL(i);r.searchParams.set("search",o),r.searchParams.set("per-page",String(s)),r.searchParams.set("select",l),t.mailto&&r.searchParams.set("mailto",t.mailto);const a=await e(r);if(!a.ok)throw new Error(`OpenAlex answered ${a.status}.`);return((await a.json()).results??[]).map(u)}}}export{p as abstractOf,h as openAlexApi};

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

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

package/dist/builtin/openalex/index.js

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

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

@@ -0,0 +1,23 @@
+import { type ApiOptions, type OpenAlexApi } from "./api.js";
+export interface OpenAlexOptions extends ApiOptions {
+    /** Papers returned. Default 5. */
+    maxResults?: number;
+    /** Abstract kept per paper. Default 400 characters. */
+    maxAbstractChars?: number;
+    /** Injected for tests, in place of the call to OpenAlex. */
+    api?: OpenAlexApi;
+}
+/**
+ * Papers on a topic from OpenAlex, as text — title, authors, venue, how often
+ * cited, a DOI, a PDF when one is open, and the start of the abstract.
+ *
+ * Free and unauthenticated. For what the literature says; not for anything
+ * recent, commercial, or outside a published paper.
+ */
+export declare function openalex(opts?: OpenAlexOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 300;
+    readonly description: "The topic, as a phrase a paper title or abstract would contain.";
+}]>>;

package/dist/builtin/openalex/openalex.js

@@ -0,0 +1 @@
+import{tool as i}from"../../tool/index.js";import{openAlexApi as c}from"./api.js";import{rendered as h}from"./render.js";const p=5,m=400;function l(t={}){const a=t.api??c(t),n=t.maxResults??p,o=t.maxAbstractChars??m;return i({name:"paper_search",effect:"readonly",trust:"external",description:"Finds published papers on a topic and returns them as text: title, authors, venue, citation count, DOI, an open PDF when there is one, 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.",args:[{name:"question",type:"string",required:!0,maxLength:300,description:"The topic, as a phrase a paper title or abstract would contain."}],run:async({question:s})=>{const e=s.trim();if(!e)throw new Error("Name the topic to search for.");const r=await a.search(e,n);if(r.length===0)throw new Error(`OpenAlex has no papers matching "${e}".`);return h(e,r,o)}})}export{l as openalex};

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

@@ -0,0 +1,2 @@
+import type { Paper } from "./api.js";
+export declare function rendered(query: string, papers: readonly Paper[], maxChars: number): string;

package/dist/builtin/openalex/render.js

@@ -0,0 +1,4 @@
+const h=3;function c(n){const t=n.authors.slice(0,3).map(e=>e.split(" ").at(-1)??e),o=n.authors.length-t.length;return t.length===0?"unknown authors":o>0?`${t.join(", ")} +${o}`:t.join(", ")}function $(n){const t=n.year===null?"":` (${n.year})`,o=n.venue?` \xB7 ${n.venue}`:"";return`${n.title}${t} \u2014 ${c(n)}${o} \xB7 ${n.citations} citations`}function d(n){const o=[n.doi?`doi:${n.doi}`:null,n.pdf?`pdf: ${n.pdf}`:null].filter(e=>e!==null);return o.length>0?o.join(" \xB7 "):null}function f(n,t){const o=n.abstract.trim();return o?o.length>t?`${o.slice(0,t).trimEnd()}\u2026`:o:null}function m(n,t,o){const e=`${t.length} paper${t.length===1?"":"s"} on "${n}", most relevant first`,u=t.map((l,s)=>[`${s+1}. ${$(l)}`,d(l),f(l,o)].filter(i=>i!==null).map((i,r)=>r===0?i:`   ${i}`).join(`
+`));return[e,...u].join(`
+
+`)}export{m as rendered};

package/dist/builtin/polite.d.ts

@@ -0,0 +1,14 @@
+export interface PoliteOptions {
+    /** Named on every request, as the open APIs ask, so a shared IP is still identifiable. */
+    userAgent: 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 a=429,_=2,c=1e3,R=5e3,u=1e4,o=t=>new Promise(e=>setTimeout(e,t));function E(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??o,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}});if(s.status!==429||r>=2)return s;await n(E(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 ("md" | "pdf" | "html" | "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,21 @@
+import { type ApiOptions, type WikidataApi } from "./api.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;
+}
+/**
+ * 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: "The thing's name, optionally followed by ': ' and what about it.";
+}]>>;

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/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;