@spendgraph/tools 0.5.0 → 0.7.0

package/dist/search/searxng/searxng.js

@@ -0,0 +1,5 @@
+import{checkUrl as S}from"../../builtin/http/allow.js";import{retrying as y}from"../retry.js";import{DEFAULT_MAX_CHARS as N,DEFAULT_MAX_RESULTS as F,NO_TOKENS as x}from"../search.js";import{textOf as A}from"./text.js";const T="searxng",U=["*"],G=2e4,X=6e3,L=4e5,H={quick:5,pro:8,deep:10},I=/https?:\/\/[^\s"'<>)\]]+/,Q=2;function W(t){return!t.url||!t.title?null:{url:t.url,title:t.title,...t.publishedDate?{date:t.publishedDate}:{},snippet:t.content??""}}function q({url:t,title:r,date:i}){return{url:t,title:r,...i?{date:i}:{}}}function K(t,r){return`## ${t.title}
+${t.url}
+${r}`}const Y=3,v=t=>t.status>=300&&t.status<400;function R(t,r){if(!r?.length)return!0;const i=new URL(t.url).hostname.toLowerCase();return r.some(u=>{const h=u.toLowerCase().replace(/^\./,"");return i===h||i.endsWith(`.${h}`)})}function z(t){const r=new Set;return t.flatMap(i=>i.hits).filter(i=>!r.has(i.url)&&r.add(i.url))}function tt(t){if(!t.baseUrl?.trim())throw new Error("searxng needs the baseUrl of a SearXNG instance, such as http://localhost:8080.");const r=t.fetch??globalThis.fetch.bind(globalThis),i=t.baseUrl.replace(/\/+$/,""),u=t.timeoutMs??G,h=Math.max(1,t.maxResults??F),g=t.maxChars??N,f=t.pageChars??X,b={...H,...t.pages},O=y(t);async function d(n,s){const e=new URL(`${i}/search`);e.searchParams.set("q",n),e.searchParams.set("format","json"),s&&e.searchParams.set("time_range",s),t.language&&e.searchParams.set("language",t.language),t.engines?.length&&e.searchParams.set("engines",t.engines.join(","));const a=await O(()=>r(e,{signal:AbortSignal.timeout(u),headers:{accept:"application/json"}}));if(!a.ok){const o=a.status===403?" SearXNG refuses the json format unless settings.yml lists it under search.formats and the limiter is off.":"";throw new Error(`SearXNG returned ${a.status}.${o}`)}const c=await a.json();return{hits:(c.results??[]).flatMap(o=>{const l=W(o);return l&&R(l,t.domains)?[l]:[]}),suggestions:c.suggestions??[]}}async function P(n,s){const e=n.suggestions.slice(0,Q);return[n,...await Promise.all(e.map(a=>d(a,s)))]}async function p(n){const s=AbortSignal.timeout(u);let e=S(n,U),a=await r(e,{signal:s,redirect:"manual"});for(let c=0;c<Y&&v(a);c++){const o=a.headers.get("location");if(!o)break;e=S(new URL(o,a.url||e).toString(),U),a=await r(e,{signal:s,redirect:"manual"})}return a}async function M(n){try{const s=await p(n.url);if(!s.ok)return n.snippet;const e=A((await s.text()).slice(0,L));return e?e.slice(0,f):n.snippet}catch{return n.snippet}}async function D(n){if(!R({url:n,snippet:""},t.domains))return null;try{const s=await p(n);return s.ok&&A((await s.text()).slice(0,L)).slice(0,f)||null}catch{return null}}const C=(n,s)=>({answer:s.slice(0,g),results:[{url:n}],model:T,truncated:s.length>g,usage:{...x,searchQueries:0}});return Object.assign(async({query:n,depth:s,recency:e})=>{const a=n.match(I)?.[0],c=a?await D(a):null;if(a&&c)return C(a,c);const o=await d(n,e),l=s==="deep"?await P(o,e):[o],w=z(l),m=w.slice(0,h),_=m.slice(0,b[s]),k=await Promise.all(_.map(M)),E=_.map(($,j)=>K($,k[j])).join(`
+
+`);return{answer:E.slice(0,g),results:m.map(q),model:T,truncated:E.length>g||w.length>m.length,usage:{...x,searchQueries:l.length}}},t.domains?.length?{domains:[...t.domains]}:{})}export{tt as searxng};

package/dist/search/searxng/text.d.ts

@@ -0,0 +1,2 @@
+/** A page's readable text: the main content where it is marked, with menus, scripts and markup gone. */
+export declare function textOf(html: string): string;

package/dist/search/searxng/text.js

@@ -0,0 +1,3 @@
+const r=/<(nav|header|footer|aside|form)\b[\s\S]*?<\/\1>/gi,c=/<(main|article)\b[^>]*>([\s\S]*?)<\/\1>/i;function t(e){return e.match(c)?.[2]??e}function a(e){return t(e).replace(/<!--[\s\S]*?-->/g," ").replace(/<script[\s\S]*?<\/script>/gi," ").replace(/<style[\s\S]*?<\/style>/gi," ").replace(/<noscript[\s\S]*?<\/noscript>/gi," ").replace(r," ").replace(/<\/(p|div|li|h[1-6]|tr|br|section|article)>/gi,`
+`).replace(/<[^>]+>/g," ").replace(/&nbsp;/g," ").replace(/&amp;/g,"&").replace(/&lt;/g,"<").replace(/&gt;/g,">").replace(/&quot;/g,'"').replace(/&#39;|&apos;/g,"'").replace(/[ \t]+/g," ").replace(/\s*\n\s*/g,`
+`).trim()}export{a as textOf};

package/dist/search/sonar/index.d.ts

@@ -0,0 +1,2 @@
+export { readReply } from "./reply.js";
+export { type SonarOptions, sonar } from "./sonar.js";

package/dist/search/sonar/index.js

@@ -0,0 +1 @@
+import{readReply as e}from"./reply.js";import{sonar as a}from"./sonar.js";export{e as readReply,a as sonar};

package/dist/search/sonar/reply.js

@@ -0,0 +1 @@
+function a(n){const s=n.search_results??[];return s.length?s.flatMap(e=>e.url?[{url:e.url,title:e.title,date:e.date}]:[]):(n.citations??[]).map(e=>({url:e}))}function l(n,s,e,r){const o=n,c=o.choices?.[0]?.message?.content??"",u=a(o),i=u.slice(0,r),t=o.usage??{};return{answer:c.slice(0,e),results:i,model:o.model??s,truncated:c.length>e||u.length>i.length,usage:{inputTokens:t.prompt_tokens??0,outputTokens:t.completion_tokens??0,citationTokens:t.citation_tokens??0,reasoningTokens:t.reasoning_tokens??0,searchQueries:t.num_search_queries??0}}}export{l as readReply};

package/dist/search/sonar/sonar.d.ts

@@ -0,0 +1,13 @@
+import { type Searcher, type SearcherOptions } from "../search.js";
+export interface SonarOptions extends SearcherOptions {
+    /** Perplexity key. Required, and read from here rather than the environment. */
+    apiKey: string;
+}
+/**
+ * The live web through Perplexity's Sonar models, one model per depth.
+ *
+ * Perplexity searches, reads and writes the answer itself, with citation
+ * marks, and bills citation and reasoning tokens on top of the usual two.
+ * The timeout defaults to a minute, or five on a deep search.
+ */
+export declare function sonar(opts: SonarOptions): Searcher;

package/dist/search/sonar/sonar.js

@@ -0,0 +1 @@
+import{retrying as m}from"../retry.js";import{DEFAULT_MAX_CHARS as d,DEFAULT_MAX_RESULTS as h}from"../search.js";import{readReply as _}from"./reply.js";const E={quick:"sonar",pro:"sonar-pro",deep:"sonar-deep-research"},f="https://api.perplexity.ai/chat/completions",p=6e4,T=3e5,u=500;function A(e){if(!e.apiKey?.trim())throw new Error("sonar needs a Perplexity apiKey; it will not read one from the process.");const i=e.fetch??globalThis.fetch.bind(globalThis),a=m(e);return Object.assign(async({query:s,depth:o,recency:n})=>{const r=E[o],c=e.timeoutMs??(o==="deep"?T:p),t=await a(()=>i(f,{method:"POST",signal:AbortSignal.timeout(c),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({model:r,messages:[{role:"user",content:s}],...n?{search_recency_filter:n}:{},...e.domains?.length?{search_domain_filter:e.domains}:{}})}));if(!t.ok){const l=(await t.text()).slice(0,u);throw new Error(`Perplexity returned ${t.status} for ${r}: ${l}`)}return _(await t.json(),r,e.maxChars??d,e.maxResults??h)},e.domains?.length?{domains:[...e.domains]}:{})}export{A as sonar};

package/dist/search/tavily/index.d.ts

@@ -0,0 +1,4 @@
+export type { TavilyReply } from "./reply.js";
+export { readReply } from "./reply.js";
+export type { TavilyOptions } from "./tavily.js";
+export { tavily } from "./tavily.js";

package/dist/search/tavily/index.js

@@ -0,0 +1 @@
+import{readReply as o}from"./reply.js";import{tavily as t}from"./tavily.js";export{o as readReply,t as tavily};

package/dist/search/tavily/reply.d.ts

@@ -0,0 +1,22 @@
+import { type Searched } from "../search.js";
+interface Hit {
+    url?: string;
+    title?: string;
+    content?: string;
+    raw_content?: string | null;
+    published_date?: string;
+}
+export interface TavilyReply {
+    answer?: string | null;
+    results?: Hit[];
+    auto_parameters?: Record<string, unknown>;
+}
+/**
+ * Tavily's reply as a `Searched`.
+ *
+ * Its own `answer` leads where it gave one, because it is a summary written
+ * across every result; the per-result text follows so a later stage can quote
+ * a source rather than the summary of it.
+ */
+export declare function readReply(raw: TavilyReply, model: string, maxChars: number, maxResults: number): Searched;
+export {};

package/dist/search/tavily/reply.js

@@ -0,0 +1,5 @@
+import{NO_TOKENS as c}from"../search.js";function i(e){return e.url?{url:e.url,...e.title?{title:e.title}:{},...e.published_date?{date:e.published_date}:{}}:null}function a(e){const t=(e.raw_content??e.content??"").trim();return`## ${e.title??e.url}
+${e.url}
+${t}`}function p(e,t,r,s){const u=(e.results??[]).filter(l=>!!l.url),n=u.slice(0,s),o=[e.answer?.trim(),...n.map(a)].filter(Boolean).join(`
+
+`);return{answer:o.slice(0,r),results:n.map(i).filter(l=>l!==null),model:t,truncated:o.length>r||u.length>n.length,usage:{...c}}}export{p as readReply};

package/dist/search/tavily/tavily.d.ts

@@ -0,0 +1,14 @@
+import { type Searcher, type SearcherOptions } from "../search.js";
+export interface TavilyOptions extends SearcherOptions {
+    /** Tavily key. Required, and read from here rather than the environment. */
+    apiKey: string;
+}
+/**
+ * The live web through Tavily, which searches and extracts in one call.
+ *
+ * Built for retrieval rather than for a person reading a results page: it
+ * returns the text of each page alongside its url, so a finding keeps both
+ * what was said and where it was said. Depth buys a wider search and more
+ * pages read, not a different model.
+ */
+export declare function tavily(opts: TavilyOptions): Searcher;

package/dist/search/tavily/tavily.js

@@ -0,0 +1 @@
+import{retrying as l}from"../retry.js";import{DEFAULT_MAX_CHARS as m,DEFAULT_MAX_RESULTS as n}from"../search.js";import{readReply as _}from"./reply.js";const u="https://api.tavily.com/search",y="tavily-search",g=6e4,p=500,T={quick:{search_depth:"basic",pages:3},pro:{search_depth:"advanced",pages:5},deep:{search_depth:"advanced",pages:10}},E={day:1,week:7,month:30,year:365};function S(e){if(!e.apiKey?.trim())throw new Error("tavily needs an apiKey; it will not read one from the process.");const i=e.fetch??globalThis.fetch.bind(globalThis),r=l(e);return Object.assign(async({query:s,depth:o,recency:t})=>{const{search_depth:c,pages:d}=T[o],a=await r(()=>i(u,{method:"POST",signal:AbortSignal.timeout(e.timeoutMs??g),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({query:s,search_depth:c,include_answer:!0,include_raw_content:!0,max_results:Math.min(d,e.maxResults??n),...t?{days:E[t]}:{},...e.domains?.length?{include_domains:e.domains}:{}})}));if(!a.ok){const h=(await a.text()).slice(0,p);throw new Error(`Tavily returned ${a.status}: ${h}`)}return _(await a.json(),y,e.maxChars??m,e.maxResults??n)},e.domains?.length?{domains:[...e.domains]}:{})}export{S as tavily};

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { type Replay, replaying, type Unrecorded } from "./replay.js";
+export { type MemorySeed, type MemoryStore, memoryStore, type ObservedMoment, type StoredMemory, } from "./store.js";

package/dist/testing/index.js

@@ -0,0 +1 @@
+import{replaying as e}from"./replay.js";import{memoryStore as p}from"./store.js";export{p as memoryStore,e as replaying};

package/dist/testing/replay.d.ts

@@ -0,0 +1,55 @@
+import type { ToolResult } from "../types/index.js";
+/** A call the recording had no answer for. */
+export interface Unrecorded {
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface ReplayOptions {
+    /**
+     * Tools that must still run for real, by name.
+     *
+     * A replay stands in for the world, not for the agent's own bookkeeping.
+     * `finish` carries the answer — the thing actually under test — so replaying
+     * it would mean a reworded prompt could only ever produce the old wording,
+     * and the run stalls the first time it says anything differently. `think` and
+     * `notes` are the same: they change nothing outside the process, so there is
+     * nothing to stand in for.
+     *
+     * Their recordings are dropped rather than kept unused, because a result
+     * nothing was ever going to ask for is not a step the new run skipped.
+     */
+    live?: readonly string[];
+    /** What runs the tools named in `live`. Required with it, and refused without. */
+    on?: {
+        invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    };
+}
+export interface Replay {
+    /** Hands back what the recording holds, or a failed result saying it does not. */
+    invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /** Calls this run made that the recording could not answer, in order. */
+    unrecorded: Unrecorded[];
+    /** Recorded results this run never asked for. */
+    unused(): ToolResult[];
+}
+/**
+ * The tool results a run already produced, handed back instead of running anything.
+ *
+ * What a recorded trace is for: re-run the reasoning against a new prompt or a
+ * new model while the tools answer exactly as they did, so the only thing that
+ * changed is the thing under test. Nothing reaches a database, an API or a
+ * customer, and the comparison is not confounded by the world having moved.
+ *
+ * Matched on the arguments as well as the name, which is the whole value and
+ * also the part that looks like a limitation. A replay that answered
+ * `track("ORD-9")` with the recording of `track("ORD-1")` would be a green run
+ * proving nothing. A call the recording cannot answer is the finding: the new
+ * prompt asked something the old one never did, and the recording is not
+ * evidence about it either way.
+ *
+ * It offers no `effectOf`, and that is not an omission. Nothing runs during a
+ * replay, so nothing is destructive — a rail that gates on effect has nothing
+ * to guard, and giving it the original effects would have it blocking calls
+ * that are already only paper.
+ */
+export declare function replaying(recorded: readonly ToolResult[], opts?: ReplayOptions): Replay;

package/dist/testing/replay.js

@@ -0,0 +1 @@
+const u=(i,n,e)=>i.name===n&&JSON.stringify(i.args)===JSON.stringify(e),f=(i,n,e)=>({name:i,args:n,status:"failed",output:"",error:`Nothing recorded for ${i}(${JSON.stringify(n)}). The recording holds: ${[...new Set(e.map(o=>o.name))].join(", ")||"nothing"}`,latencyMs:0});function l(i,n={}){const e=new Set(n.live??[]);if(e.size>0&&!n.on)throw new Error(`replaying names ${[...e].join(", ")} as live, but nothing to run them on.`);const o=i.filter(t=>!e.has(t.name)),s=new Set,c=[];return{unrecorded:c,unused:()=>o.filter((t,r)=>!s.has(r)),invoke:async(t,r)=>{if(e.has(t))return n.on.invoke(t,r);const a=o.findIndex((d,h)=>!s.has(h)&&u(d,t,r));return a===-1?(c.push({name:t,args:r}),f(t,r,o)):(s.add(a),{...o[a]})}}}export{l as replaying};

package/dist/testing/store.d.ts

@@ -0,0 +1,35 @@
+import type { MemoryClient, MemorySource } from "../memories/client.js";
+export interface StoredMemory {
+    id: string;
+    context: string;
+    kind: string;
+    source: string;
+    text: string;
+    details: Record<string, unknown>;
+    extends: string[];
+    related_to: string[];
+    reinforces: string[];
+    contradicts: string[];
+}
+export interface ObservedMoment {
+    source: string;
+    payload: string | Record<string, unknown>;
+    stream?: string;
+}
+export interface MemorySeed {
+    context: string;
+    text: string;
+    details?: Record<string, unknown>;
+    kind?: string;
+    source?: MemorySource;
+    extends?: string[];
+    related_to?: string[];
+    reinforces?: string[];
+    contradicts?: string[];
+}
+export interface MemoryStore extends MemoryClient {
+    memories: StoredMemory[];
+    observed: ObservedMoment[];
+    remember(seed: MemorySeed): StoredMemory;
+}
+export declare function memoryStore(seeds?: MemorySeed[]): MemoryStore;

package/dist/testing/store.js

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

package/dist/tool/bind.js

@@ -1,64 +1 @@
-import { tool } from "./tool.js";
-export class ToolDriftError extends Error {
-    toolName;
-    differences;
-    constructor(toolName, differences) {
-        super(`Tool "${toolName}" is stored differently from the code binding it: ${differences.join("; ")}.`);
-        this.toolName = toolName;
-        this.differences = differences;
-        this.name = "ToolDriftError";
-    }
-}
-export class ToolNotStoredError extends Error {
-    toolName;
-    constructor(toolName) {
-        super(`No stored tool named "${toolName}".`);
-        this.toolName = toolName;
-        this.name = "ToolNotStoredError";
-    }
-}
-function drift(declared, stored) {
-    const out = [];
-    const byName = new Map(stored.map((a) => [a.name, a]));
-    for (const arg of declared) {
-        const found = byName.get(arg.name);
-        if (!found) {
-            out.push(`"${arg.name}" is declared here but not stored`);
-            continue;
-        }
-        byName.delete(arg.name);
-        if (found.type !== arg.type) {
-            out.push(`"${arg.name}" is ${arg.type} here and ${found.type} stored`);
-        }
-        if (found.required !== arg.required) {
-            out.push(`"${arg.name}" is ${arg.required ? "required" : "optional"} here and the reverse stored`);
-        }
-    }
-    for (const name of byName.keys()) {
-        out.push(`"${name}" is stored but not declared here`);
-    }
-    return out;
-}
-export async function bindTool(sg, spec, query = {}) {
-    let stored;
-    try {
-        ({ tool: stored } = await sg.tools.get(spec.name, query));
-    }
-    catch (err) {
-        if (err && typeof err === "object" && "status" in err && err.status === 404) {
-            throw new ToolNotStoredError(spec.name);
-        }
-        throw err;
-    }
-    const differences = drift(spec.args, stored.args ?? []);
-    if (differences.length)
-        throw new ToolDriftError(spec.name, differences);
-    return tool({
-        name: stored.name,
-        description: stored.description,
-        args: spec.args,
-        effect: stored.effect ?? undefined,
-        pinned: stored.pinned,
-        run: spec.run,
-    });
-}
+import{tool as i}from"./tool.js";class a extends Error{toolName;differences;constructor(r,t){super(`Tool "${r}" is stored differently from the code binding it: ${t.join("; ")}.`),this.toolName=r,this.differences=t,this.name="ToolDriftError"}}class d extends Error{toolName;constructor(r){super(`No stored tool named "${r}".`),this.toolName=r,this.name="ToolNotStoredError"}}function f(s,r){const t=[],o=new Map(r.map(e=>[e.name,e]));for(const e of s){const n=o.get(e.name);if(!n){t.push(`"${e.name}" is declared here but not stored`);continue}o.delete(e.name),n.type!==e.type&&t.push(`"${e.name}" is ${e.type} here and ${n.type} stored`),n.required!==e.required&&t.push(`"${e.name}" is ${e.required?"required":"optional"} here and the reverse stored`)}for(const e of o.keys())t.push(`"${e}" is stored but not declared here`);return t}async function c(s,r,t={}){let o;try{({tool:o}=await s.tools.get(r.name,t))}catch(n){throw n&&typeof n=="object"&&"status"in n&&n.status===404?new d(r.name):n}const e=f(r.args,o.args??[]);if(e.length)throw new a(r.name,e);return i({name:o.name,description:o.description,args:r.args,effect:o.effect??void 0,pinned:o.pinned,run:r.run})}export{a as ToolDriftError,d as ToolNotStoredError,c as bindTool};

package/dist/tool/index.js

@@ -1,2 +1 @@
-export { bindTool, ToolDriftError, ToolNotStoredError } from "./bind.js";
-export { tool } from "./tool.js";
+import{bindTool as t,ToolDriftError as l,ToolNotStoredError as e}from"./bind.js";import{tool as T}from"./tool.js";export{l as ToolDriftError,e as ToolNotStoredError,t as bindTool,T as tool};

package/dist/tool/tool.d.ts

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

package/dist/tool/tool.js

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

package/dist/types/index.d.ts

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

package/dist/types/index.js

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

package/dist/types/result.d.ts

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

package/dist/types/result.js

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

package/dist/types/tool.d.ts

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

package/dist/types/tool.js

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

package/dist/wire/index.js

@@ -1,3 +1 @@
-export { toJsonSchema, } from "./json-schema.js";
-export { toMarkdown } from "./markdown.js";
-export { toAnthropic, toOpenAI, } from "./providers.js";
+import{toJsonSchema as t}from"./json-schema.js";import{toMarkdown as p}from"./markdown.js";import{toAnthropic as n,toOpenAI as f}from"./providers.js";export{n as toAnthropic,t as toJsonSchema,p as toMarkdown,f as toOpenAI};

package/dist/wire/json-schema.js

@@ -1,65 +1 @@
-export const JSON_TYPE = {
-    string: "string",
-    text: "string",
-    number: "number",
-    boolean: "boolean",
-    enum: "string",
-    list: "array",
-    json: "object",
-};
-function coerceDefault(field) {
-    const raw = field.default;
-    if (raw === undefined)
-        return undefined;
-    switch (field.type) {
-        case "number": {
-            const n = Number(raw);
-            return Number.isFinite(n) ? n : undefined;
-        }
-        case "boolean": {
-            const t = raw.trim().toLowerCase();
-            if (t === "true" || t === field.trueText?.trim().toLowerCase())
-                return true;
-            if (t === "false" || t === field.falseText?.trim().toLowerCase())
-                return false;
-            return undefined;
-        }
-        case "enum":
-            return field.options?.includes(raw) ? raw : undefined;
-        case "list":
-        case "json":
-            return undefined;
-        default:
-            return raw;
-    }
-}
-export function toJsonSchema(args) {
-    const properties = {};
-    for (const field of args) {
-        const property = { type: JSON_TYPE[field.type] };
-        if (field.description)
-            property.description = field.description;
-        if (field.type === "enum" && field.options?.length)
-            property.enum = [...field.options];
-        if (field.type === "list")
-            property.items = { type: "string" };
-        if (field.type === "number") {
-            if (field.min !== undefined)
-                property.minimum = field.min;
-            if (field.max !== undefined)
-                property.maximum = field.max;
-        }
-        if ((field.type === "string" || field.type === "text") && field.maxLength !== undefined) {
-            property.maxLength = field.maxLength;
-        }
-        const fallback = coerceDefault(field);
-        if (fallback !== undefined)
-            property.default = fallback;
-        properties[field.name] = property;
-    }
-    return {
-        type: "object",
-        properties,
-        required: args.filter((a) => a.required).map((a) => a.name),
-    };
-}
+const o={string:"string",text:"string",number:"number",boolean:"boolean",enum:"string",list:"array",json:"object"};function u(t){const n=t.default;if(n!==void 0)switch(t.type){case"number":{const e=Number(n);return Number.isFinite(e)?e:void 0}case"boolean":{const e=n.trim().toLowerCase();return e==="true"||e===t.trueText?.trim().toLowerCase()?!0:e==="false"||e===t.falseText?.trim().toLowerCase()?!1:void 0}case"enum":return t.options?.includes(n)?n:void 0;case"list":case"json":return;default:return n}}function s(t){const n={};for(const e of t){const r={type:o[e.type]};e.description&&(r.description=e.description),e.type==="enum"&&e.options?.length&&(r.enum=[...e.options]),e.type==="list"&&(r.items={type:"string"}),e.type==="number"&&(e.min!==void 0&&(r.minimum=e.min),e.max!==void 0&&(r.maximum=e.max)),(e.type==="string"||e.type==="text")&&e.maxLength!==void 0&&(r.maxLength=e.maxLength);const i=u(e);i!==void 0&&(r.default=i),n[e.name]=r}return{type:"object",properties:n,required:t.filter(e=>e.required).map(e=>e.name)}}export{o as JSON_TYPE,s as toJsonSchema};

package/dist/wire/markdown.d.ts

@@ -2,8 +2,10 @@ import type { ToolDeclaration } from "../types/index.js";
 /**
  * Declarations as markdown, for a model with no tools API.
  *
- * About a quarter cheaper than the JSON, since JSON Schema is mostly
- * scaffolding — but you give up structured tool calls and parse intent out of
- * prose instead. Only worth it where there is no native `tools` array.
+ * A third to two fifths cheaper than the JSON, since JSON Schema is mostly
+ * scaffolding — 31% under the Anthropic shape on a bus of nine tools, 38% on a
+ * bus of three, and more again against OpenAI's extra envelope. But you give up
+ * structured tool calls and parse intent out of prose instead. Only worth it
+ * where there is no native `tools` array.
  */
 export declare function toMarkdown(decls: ToolDeclaration[], heading?: string): string;