@spendgraph/tools 0.6.0 → 0.7.0

package/dist/memories/recall/recall.js

@@ -0,0 +1 @@
+import{tool as f}from"../../tool/index.js";import{contextIds as l,fixedRoot as h,rootOf as p}from"../context.js";import{readSubgraph as x}from"../explore/subgraph.js";import{rendered as y}from"./render.js";const g="toon",u=10,w=50,I=3;async function T(e,n){if(!e.supersede||!n)return;const o=n.indexOf(":"),s=x(await e.client.getContextGraph({contextType:n.slice(0,o),contextName:n.slice(o+1),depth:I,...e.graphId?{graphId:e.graphId}:{}})),a=new Map;for(const r of s.edges)r.link_type==="contradicts"&&a.set(r.to,r.from);return r=>r.context_ids.map(t=>a.get(t)).find(t=>t!==void 0)}function k(e){const n=e.rootContextId!==void 0,o=h(e.rootContextId)??"your root";return f({name:"recall",effect:"readonly",description:"Searches your own memory for what was recorded about something and returns the matching notes, one per row with the contexts each is filed under. Cheap, so try it before a web search and before deep_recall. Use deep_recall instead when the answer is spread across several notes or needs a why. Ask one focused thing.",args:[{name:"question",type:"string",required:!0,maxLength:1e3,description:"What you want to know, in a sentence."},{name:"context_ids",type:"list",required:!1,description:n?`Contexts under ${o} to favour, as type:name. Take them from an earlier result or from explore_memory.`:"Only search these contexts, as type:name. Take them from an earlier result or from explore_memory."},{name:"limit",type:"number",required:!1,min:1,max:w,description:`Most notes to return. Default ${e.limit??u}.`}],run:async({question:s,context_ids:a,limit:r})=>{const t=p(e.rootContextId),i=l(a,e.defaultContextType),d=t?[t]:i,c=t&&i?i:void 0,m=(await e.client.retrieveMemories({query:s,limit:r??e.limit??u,format:"json",...e.graphId?{graphId:e.graphId}:{},...d?{contextIds:d}:{},...c?{boostContextIds:c}:{},...e.sources?.length?{sources:e.sources}:{}})).items??[];return m.length===0?"Nothing recorded about that.":y(m,e.format??g,await T(e,t))}})}export{k as recall};

package/dist/memories/recall/render.d.ts

@@ -0,0 +1,5 @@
+import type { RecalledItem } from "../client.js";
+export type RecallFormat = "toon" | "markdown";
+/** Which context superseded this note's, when one did. */
+export type Superseded = (item: RecalledItem) => string | undefined;
+export declare const rendered: (items: RecalledItem[], format: RecallFormat, by?: Superseded) => string;

package/dist/memories/recall/render.js

@@ -0,0 +1,3 @@
+const t=/[,:"\n\\]|^\s|\s$|^$/,d=n=>t.test(n)?`"${n.replace(/\\/g,"\\\\").replace(/"/g,'\\"').replace(/\n/g,"\\n")}"`:n,c=n=>String(Math.round(n*100)),$=(n,o,e)=>[n.context_ids.join(";"),n.text,n.source??"",c(n.score),...e?[o??""]:[]],a=(n,o)=>{const e=o?"contexts,text,source,relevance,superseded_by":"contexts,text,source,relevance";return[`memories[${n.length}]{${e}}:`,...n.map(s=>`  ${$(s,o?.(s),o!==void 0).map(d).join(",")}`)].join(`
+`)},p=(n,o)=>n.map(e=>{const s=o?.(e),r=s?` \u2014 superseded by ${s}`:"";return`- [${e.context_ids.join(", ")}] ${e.text} (${e.source??"unknown"}, ${c(e.score)}%)${r}`}).join(`
+`),u=(n,o,e)=>o==="toon"?a(n,e):p(n,e);export{u as rendered};

package/dist/memories/remember/remember.d.ts

@@ -0,0 +1,49 @@
+import type { MemoryGraph, MemorySource } from "../client.js";
+export interface RememberOptions extends MemoryGraph {
+    source?: MemorySource;
+    defaultContextType?: string;
+}
+export declare function remember(opts: RememberOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "context";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 200;
+    readonly description: "Where it is filed, as type:name.";
+}, {
+    readonly name: "text";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 4000;
+    readonly description: "The thing to remember, as a complete sentence or two.";
+}, {
+    readonly name: "kind";
+    readonly type: "enum";
+    readonly required: false;
+    readonly options: readonly ["fact", "decision", "constraint", "feedback", "observation"];
+    readonly description: "What sort of thing it is. Default fact.";
+}, {
+    readonly name: "details";
+    readonly type: "json";
+    readonly required: false;
+    readonly description: string;
+}, {
+    readonly name: "extends";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: "Contexts this is a more specific detail of, as type:name.";
+}, {
+    readonly name: "related_to";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: "Contexts this sits alongside, as type:name.";
+}, {
+    readonly name: "reinforces";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: "Contexts this backs up with more evidence, as type:name.";
+}, {
+    readonly name: "contradicts";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: "Contexts this supersedes, as type:name.";
+}]>>;

package/dist/memories/remember/remember.js

@@ -0,0 +1 @@
+import{tool as h}from"../../tool/index.js";import{contextId as y,contextIds as a,fixedRoot as x,rootOf as w}from"../context.js";const g=["fact","decision","constraint","feedback","observation"],b="assistant",C=e=>typeof e=="object"&&e!==null&&!Array.isArray(e),q=(e,t)=>{if(t==null)return{data:e};if(!C(t))throw new Error("details must be a JSON object of named fields.");return{...t,data:e}},d=(e,t)=>t?.length?{[e]:t}:{};function v(e){const t=e.defaultContextType,u=e.rootContextId===void 0?"":` under ${x(e.rootContextId)??"your root"}`,m=(c,l)=>{const s=w(e.rootContextId),i=a(l,t)??[],r=s?[s,...i]:i;return[...new Set(r)].filter(n=>n!==c)};return h({name:"remember",effect:"idempotent",description:`Records one thing in your own memory${u} so a later run can recall it. File it under a context named type:name, like person:alice or decision:pricing_tier, reusing a name from explore_memory when one fits. One fact per call; the text should stand on its own without the conversation around it.`,args:[{name:"context",type:"string",required:!0,maxLength:200,description:"Where it is filed, as type:name."},{name:"text",type:"string",required:!0,maxLength:4e3,description:"The thing to remember, as a complete sentence or two."},{name:"kind",type:"enum",required:!1,options:g,description:"What sort of thing it is. Default fact."},{name:"details",type:"json",required:!1,description:"Structured fields worth keeping with the note, as a JSON object: amounts, dates, ids, URLs. The text is still what a recall shows; these ride along with it."},{name:"extends",type:"list",required:!1,description:"Contexts this is a more specific detail of, as type:name."},{name:"related_to",type:"list",required:!1,description:"Contexts this sits alongside, as type:name."},{name:"reinforces",type:"list",required:!1,description:"Contexts this backs up with more evidence, as type:name."},{name:"contradicts",type:"list",required:!1,description:"Contexts this supersedes, as type:name."}],run:async({context:c,text:l,kind:s="fact",details:i,...r})=>{const n=y(c,t),f={event_kind:s,context_id:n,source:e.source??b,payload:q(l,i),...d("extends",m(n,r.extends)),...d("related_to",a(r.related_to,t)),...d("reinforces",a(r.reinforces,t)),...d("contradicts",a(r.contradicts,t))},p=await e.client.storeEventsBatch([f],e.graphId),[o]=p.results;if(!o||o.status==="error")throw new Error(o?.error??"The memory was not stored, and the server did not say why.");return o.status==="filtered"?{stored:!1,context:n,reason:o.error??"judged not worth keeping"}:{stored:!0,context:n,relevance:o.relevance}}})}export{v as remember};

package/dist/search/index.d.ts

@@ -0,0 +1,5 @@
+export type { Recency, SearchAsk, SearchDepth, Searched, Searcher, SearcherOptions, SearchUsage, Source, } from "./search.js";
+export { DEPTHS, NO_TOKENS } from "./search.js";
+export { type SearxngOptions, searxng, textOf } from "./searxng/index.js";
+export { type TavilyOptions, tavily } from "./tavily/index.js";
+export { readReply, type SonarOptions, sonar } from "./sonar/index.js";

package/dist/search/index.js

@@ -0,0 +1 @@
+import{DEPTHS as e,NO_TOKENS as t}from"./search.js";import{searxng as f,textOf as p}from"./searxng/index.js";import{tavily as m}from"./tavily/index.js";import{readReply as l,sonar as n}from"./sonar/index.js";export{e as DEPTHS,t as NO_TOKENS,l as readReply,f as searxng,n as sonar,m as tavily,p as textOf};

package/dist/search/retry.d.ts

@@ -0,0 +1,6 @@
+import type { SearcherOptions } from "./search.js";
+/**
+ * Sends again while the answer is a 429 or a 5xx and tries remain, then hands
+ * back whatever came last, ok or not, for the caller to read or refuse.
+ */
+export declare function retrying(opts: Pick<SearcherOptions, "attempts" | "sleep" | "random">): (send: () => Promise<Response>) => Promise<Response>;

package/dist/search/retry.js

@@ -0,0 +1 @@
+const M=500,f=8e3;function m(t){const r=t.headers.get("retry-after");if(!r)return null;const e=Number(r);return Number.isFinite(e)&&e>=0?e*1e3:null}const u=t=>t===429||t>=500;function A(t){const r=Math.max(1,t.attempts??3),e=t.sleep??(o=>new Promise(n=>setTimeout(n,o))),c=t.random??Math.random;return async o=>{for(let n=1;;n++){const s=await o();if(s.ok||!u(s.status)||n===r)return s;const a=Math.min(8e3,500*2**(n-1)),i=m(s)??a;await e(i+a*c())}}}export{A as retrying};

package/dist/search/search.d.ts

@@ -0,0 +1,63 @@
+/** How much searching one call is worth. */
+export type SearchDepth = "quick" | "pro" | "deep";
+export declare const DEPTHS: readonly SearchDepth[];
+export type Recency = "day" | "week" | "month" | "year";
+export interface Source {
+    url: string;
+    title?: string;
+    date?: string;
+}
+export interface SearchUsage {
+    inputTokens: number;
+    outputTokens: number;
+    citationTokens: number;
+    reasoningTokens: number;
+    searchQueries: number;
+}
+/** What every searcher hands back, whoever did the searching. */
+export interface Searched {
+    answer: string;
+    results: Source[];
+    model: string;
+    truncated: boolean;
+    usage: SearchUsage;
+}
+export interface SearchAsk {
+    query: string;
+    depth: SearchDepth;
+    recency?: Recency;
+}
+export type Searcher = ((ask: SearchAsk) => Promise<Searched>) & {
+    domains?: readonly string[];
+};
+/** What every searcher is configured with; each adds only where its answers come from. */
+export interface SearcherOptions {
+    /** Hosts results are restricted to. Set here, so the model cannot widen it. */
+    domains?: string[];
+    /** Give up on a request after this. */
+    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 the other 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;
+}
+export declare const DEFAULT_MAX_CHARS = 20000;
+export declare const DEFAULT_MAX_RESULTS = 20;
+export declare const NO_TOKENS: SearchUsage;

package/dist/search/search.js

@@ -0,0 +1 @@
+const o=["quick","pro","deep"],e=2e4,t=20,n={inputTokens:0,outputTokens:0,citationTokens:0,reasoningTokens:0,searchQueries:1};export{e as DEFAULT_MAX_CHARS,t as DEFAULT_MAX_RESULTS,o as DEPTHS,n as NO_TOKENS};

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

@@ -0,0 +1,2 @@
+export { type SearxngOptions, searxng } from "./searxng.js";
+export { textOf } from "./text.js";

package/dist/search/searxng/index.js

@@ -0,0 +1 @@
+import{searxng as o}from"./searxng.js";import{textOf as x}from"./text.js";export{o as searxng,x as textOf};

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

@@ -0,0 +1,14 @@
+import { type SearchDepth, type Searcher, type SearcherOptions } from "../search.js";
+export interface SearxngOptions extends SearcherOptions {
+    /** The SearXNG instance, such as http://localhost:8080. Required. */
+    baseUrl: string;
+    /** Pin which engines answer. Default: whatever the instance runs. */
+    engines?: string[];
+    /** Pin the language. Default: the instance's own. */
+    language?: string;
+    /** Text kept from each page read. Default 6000 characters. */
+    pageChars?: number;
+    /** Pages read at each depth. Default 5, 8 and 10. */
+    pages?: Partial<Record<SearchDepth, number>>;
+}
+export declare function searxng(opts: SearxngOptions): Searcher;

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/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/tool.d.ts

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

package/dist/types/index.d.ts

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

package/dist/types/result.d.ts

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

package/dist/types/tool.d.ts

@@ -66,6 +66,22 @@ export type ArgsOf<T extends readonly ArgSpec[]> = {
  * the same as safe.
  */
 export type Effect = "readonly" | "idempotent" | "destructive";
+/**
+ * Where what a tool returns came from.
+ *
+ * `own` is yours: a database you run, a file you wrote, a calculation. `external`
+ * is content from outside that somebody else can write — a fetched page, a
+ * search result, an inbox, a document a customer uploaded. What comes back from
+ * one of those is data, and anything in it that reads like an instruction was
+ * put there by whoever controls the source.
+ *
+ * Declared rather than inferred, and separate from `effect`, because the two are
+ * independent: reading a web page is `readonly` and `external`, reading your own
+ * ledger is `readonly` and `own`, and only the first can carry an instruction
+ * written by a stranger. Unset means nobody has said, which is not the same as
+ * safe.
+ */
+export type Trust = "own" | "external";
 /**
  * A description the model reads and a function you wrote, in one object.
  *
@@ -97,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. */