@spendgraph/tools 0.5.0 → 0.7.0

package/dist/builtin/json/json.js

@@ -1,37 +1 @@
-import { tool } from "../../tool/index.js";
-import { readPath } from "./path.js";
-const DEFAULT_MAX_CHARS = 20_000;
-export function jsonQuery(opts = {}) {
-    const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
-    return tool({
-        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: true, maxLength: 200_000 },
-            { name: "path", type: "string", required: true, maxLength: 500 },
-        ],
-        run: ({ json, path }) => {
-            let document;
-            try {
-                document = JSON.parse(json);
-            }
-            catch (err) {
-                throw new Error(`json is not valid JSON: ${err.message}`);
-            }
-            const value = readPath(document, path);
-            if (value === undefined)
-                return { found: false, path, value: null };
-            const rendered = JSON.stringify(value) ?? "null";
-            return {
-                found: true,
-                path,
-                value,
-                truncated: rendered.length > maxChars,
-                ...(rendered.length > maxChars ? { value: `${rendered.slice(0, maxChars)}…` } : {}),
-            };
-        },
-    });
-}
+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/json/path.js

@@ -1,56 +1 @@
-function parsePath(path) {
-    const segments = [];
-    for (const part of path.split(".")) {
-        if (!part)
-            continue;
-        const [, name, brackets] = /^([^[\]]*)((?:\[[^\]]*\])*)$/.exec(part) ?? [];
-        if (name === undefined)
-            throw new Error(`"${part}" is not a path segment.`);
-        if (name)
-            segments.push({ kind: "key", name });
-        for (const [, inner] of (brackets ?? "").matchAll(/\[([^\]]*)\]/g)) {
-            if (inner === "*") {
-                segments.push({ kind: "all" });
-                continue;
-            }
-            const at = Number(inner);
-            if (!Number.isInteger(at))
-                throw new Error(`"[${inner}]" is not an index or a *.`);
-            segments.push({ kind: "index", at });
-        }
-    }
-    return segments;
-}
-function step(value, segment) {
-    if (value === null || value === undefined)
-        return undefined;
-    if (segment.kind === "key") {
-        if (typeof value !== "object" || Array.isArray(value))
-            return undefined;
-        return value[segment.name];
-    }
-    if (!Array.isArray(value))
-        return undefined;
-    if (segment.kind === "index") {
-        return value.at(segment.at);
-    }
-    return value;
-}
-export function readPath(document, path) {
-    let cursor = document;
-    let spread = false;
-    for (const segment of parsePath(path)) {
-        if (segment.kind === "all") {
-            if (!Array.isArray(cursor))
-                return undefined;
-            cursor = spread ? cursor.flat() : [...cursor];
-            spread = true;
-            continue;
-        }
-        cursor =
-            spread && Array.isArray(cursor)
-                ? cursor.map((item) => step(item, segment))
-                : step(cursor, segment);
-    }
-    return cursor;
-}
+function a(r){const e=[];for(const n of r.split(".")){if(!n)continue;const[,t,i]=/^([^[\]]*)((?:\[[^\]]*\])*)$/.exec(n)??[];if(t===void 0)throw new Error(`"${n}" is not a path segment.`);t&&e.push({kind:"key",name:t});for(const[,f]of(i??"").matchAll(/\[([^\]]*)\]/g)){if(f==="*"){e.push({kind:"all"});continue}const o=Number(f);if(!Number.isInteger(o))throw new Error(`"[${f}]" is not an index or a *.`);e.push({kind:"index",at:o})}}return e}function s(r,e){if(r!=null){if(e.kind==="key")return typeof r!="object"||Array.isArray(r)?void 0:r[e.name];if(Array.isArray(r))return e.kind==="index"?r.at(e.at):r}}function d(r,e){let n=r,t=!1;for(const i of a(e)){if(i.kind==="all"){if(!Array.isArray(n))return;n=t?n.flat():[...n],t=!0;continue}n=t&&Array.isArray(n)?n.map(f=>s(f,i)):s(n,i)}return n}export{d as readPath};

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/think/index.js

@@ -1 +1 @@
-export { think } from "./think.js";
+import{think as t}from"./think.js";export{t as think};

package/dist/builtin/think/think.js

@@ -1,12 +1 @@
-import { tool } from "../../tool/index.js";
-export function think() {
-    return tool({
-        name: "think",
-        effect: "readonly",
-        description: "Think a step through before acting. Use it to check a plan against the rules, " +
-            "to work out what is still missing, or to decide between two tools. It changes " +
-            "nothing and returns nothing — it is scratch space, not an answer.",
-        args: [{ name: "thought", type: "text", required: true, maxLength: 4000 }],
-        run: () => "noted",
-    });
-}
+import{tool as t}from"../../tool/index.js";function n(){return t({name:"think",effect:"readonly",description:"Think a step through before acting. Use it to check a plan against the rules, to work out what is still missing, or to decide between two tools. It changes nothing and returns nothing \u2014 it is scratch space, not an answer.",args:[{name:"thought",type:"text",required:!0,maxLength:4e3}],run:()=>"noted"})}export{n as think};

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

@@ -1 +1 @@
-export { webSearch } from "./web-search.js";
+import{webSearch as o}from"./web-search.js";export{o as webSearch};

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

@@ -1,42 +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.
-     */
-    attempts?: number;
-    /** Injected for tests. */
-    fetch?: typeof fetch;
-    /** Injected for tests. */
-    sleep?: (ms: number) => Promise<void>;
 }
 /**
- * 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 [{
@@ -50,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,103 +1 @@
-import { tool } from "../../tool/index.js";
-import { readReply } from "./reply.js";
-const DEPTHS = ["quick", "pro", "deep"];
-const MODELS = {
-    quick: "sonar",
-    pro: "sonar-pro",
-    deep: "sonar-deep-research",
-};
-const ENDPOINT = "https://api.perplexity.ai/chat/completions";
-const DEFAULT_TIMEOUT_MS = 60_000;
-const DEEP_TIMEOUT_MS = 300_000;
-const DEFAULT_MAX_CHARS = 20_000;
-const DEFAULT_MAX_RESULTS = 20;
-const ERROR_DETAIL_CHARS = 500;
-const BACKOFF_BASE_MS = 500;
-const MAX_BACKOFF_MS = 8_000;
-function retryAfterMs(res) {
-    const raw = res.headers.get("retry-after");
-    if (!raw)
-        return null;
-    const seconds = Number(raw);
-    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
-}
-const isWorthRetrying = (status) => status === 429 || status >= 500;
-function describe(maxDepth, domains) {
-    return ("Searches the live web and returns an answer with the sources it rests on. Use it for " +
-        "anything that turns on current facts — prices, releases, who holds a post, what " +
-        "changed. quick is one pass and is right for most lookups; pro searches wider and cites " +
-        "more." +
-        (maxDepth === "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.") +
-        (domains?.length ? ` Results come only from ${domains.join(", ")}.` : ""));
-}
-export function webSearch(opts) {
-    if (!opts.apiKey?.trim()) {
-        throw new Error("webSearch needs a Perplexity apiKey; it will not read one from the process.");
-    }
-    const doFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
-    const maxDepth = opts.maxDepth ?? "pro";
-    const attempts = Math.max(1, opts.attempts ?? 3);
-    const pause = opts.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
-    return tool({
-        name: "web_search",
-        description: describe(maxDepth, opts.domains),
-        effect: "readonly",
-        args: [
-            {
-                name: "query",
-                type: "string",
-                required: true,
-                maxLength: 1000,
-                description: "What to find out, as a question. One thing, not several.",
-            },
-            {
-                name: "depth",
-                type: "enum",
-                required: false,
-                options: ["quick", "pro", "deep"],
-                description: "Default quick. Raise it only when a first pass would not settle it.",
-            },
-            {
-                name: "recency",
-                type: "enum",
-                required: false,
-                options: ["day", "week", "month", "year"],
-                description: "Only consider pages published within this. Leave unset for anything.",
-            },
-        ],
-        run: async ({ query, depth = "quick", recency }) => {
-            if (DEPTHS.indexOf(depth) > DEPTHS.indexOf(maxDepth)) {
-                throw new Error(`web_search was asked for "${depth}", above the "${maxDepth}" this deployment allows.`);
-            }
-            const model = MODELS[depth];
-            const fallback = depth === "deep" ? DEEP_TIMEOUT_MS : DEFAULT_TIMEOUT_MS;
-            for (let attempt = 1;; attempt++) {
-                const res = await doFetch(ENDPOINT, {
-                    method: "POST",
-                    signal: AbortSignal.timeout(opts.timeoutMs ?? fallback),
-                    headers: {
-                        authorization: `Bearer ${opts.apiKey}`,
-                        "content-type": "application/json",
-                    },
-                    body: JSON.stringify({
-                        model,
-                        messages: [{ role: "user", content: query }],
-                        ...(recency ? { search_recency_filter: recency } : {}),
-                        ...(opts.domains?.length ? { search_domain_filter: opts.domains } : {}),
-                    }),
-                });
-                if (res.ok) {
-                    return readReply(await res.json(), model, opts.maxChars ?? DEFAULT_MAX_CHARS, opts.maxResults ?? DEFAULT_MAX_RESULTS);
-                }
-                const detail = (await res.text()).slice(0, ERROR_DETAIL_CHARS);
-                if (!isWorthRetrying(res.status) || attempt === attempts) {
-                    throw new Error(`Perplexity returned ${res.status} for ${model}: ${detail}`);
-                }
-                const wait = retryAfterMs(res) ?? BACKOFF_BASE_MS * 2 ** (attempt - 1);
-                await pause(Math.min(MAX_BACKOFF_MS, wait));
-            }
-        },
-    });
-}
+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.";
+}]>>;