@spendgraph/tools 0.5.0 → 0.7.0

package/dist/builtin/date/date.js

@@ -1,41 +1 @@
-import { tool } from "../../tool/index.js";
-import { between, parseDate, shift } from "./shift.js";
-const UNITS = ["seconds", "minutes", "hours", "days", "weeks", "months", "years"];
-export function dateMath() {
-    return tool({
-        name: "date_math",
-        effect: "readonly",
-        description: "Works out a date exactly. `add` and `subtract` move a date by an amount of a " +
-            "unit; `difference` says how far apart two dates are in whole units. Use it for " +
-            "deadlines, notice periods, ages and 'how long ago' — never work a date out yourself.",
-        args: [
-            {
-                name: "operation",
-                type: "enum",
-                required: true,
-                options: ["add", "subtract", "difference"],
-            },
-            { name: "date", type: "string", required: true, description: "ISO, as in 2026-03-31." },
-            { name: "unit", type: "enum", required: true, options: [...UNITS] },
-            { name: "amount", type: "number", required: false, description: "For add and subtract." },
-            {
-                name: "to",
-                type: "string",
-                required: false,
-                description: "The other date, for difference.",
-            },
-        ],
-        run: ({ operation, date, unit, amount, to }) => {
-            const from = parseDate(date, "date");
-            if (operation === "difference") {
-                if (!to)
-                    throw new Error("difference needs a second date in `to`.");
-                return { unit, difference: between(from, parseDate(to, "to"), unit) };
-            }
-            if (amount === undefined)
-                throw new Error(`${operation} needs an \`amount\`.`);
-            const moved = shift(from, operation === "subtract" ? -amount : amount, unit);
-            return { iso: moved.toISOString(), date: moved.toISOString().slice(0, 10) };
-        },
-    });
-}
+import{tool as i}from"../../tool/index.js";import{between as u,parseDate as d,shift as f}from"./shift.js";const y=["seconds","minutes","hours","days","weeks","months","years","weekdays"],c=["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"];function h(){return i({name:"date_math",effect:"readonly",description:"Works out a date exactly. `add` and `subtract` move a date by an amount of a unit; `difference` says how far apart two dates are in whole units. `weekdays` is Monday to Friday, for anything written in working days; it knows nothing about holidays. Use it for deadlines, notice periods, ages and 'how long ago' \u2014 never work a date out yourself.",args:[{name:"operation",type:"enum",required:!0,options:["add","subtract","difference"]},{name:"date",type:"string",required:!0,description:"ISO, as in 2026-03-31."},{name:"unit",type:"enum",required:!0,options:[...y]},{name:"amount",type:"number",required:!1,description:"For add and subtract."},{name:"to",type:"string",required:!1,description:"The other date, for difference."}],run:({operation:e,date:s,unit:t,amount:r,to:n})=>{const o=d(s,"date");if(e==="difference"){if(!n)throw new Error("difference needs a second date in `to`.");return{unit:t,difference:u(o,d(n,"to"),t)}}if(r===void 0)throw new Error(`${e} needs an \`amount\`.`);const a=f(o,e==="subtract"?-r:r,t);return{iso:a.toISOString(),date:a.toISOString().slice(0,10),weekday:c[a.getUTCDay()]}}})}export{h as dateMath};

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

@@ -1,2 +1,3 @@
 export { dateMath } from "./date.js";
 export { between, parseDate, shift, type Unit } from "./shift.js";
+export { dates } from "./words.js";

package/dist/builtin/date/index.js

@@ -1,2 +1 @@
-export { dateMath } from "./date.js";
-export { between, parseDate, shift } from "./shift.js";
+import{dateMath as r}from"./date.js";import{between as a,parseDate as f,shift as p}from"./shift.js";import{dates as s}from"./words.js";export{a as between,r as dateMath,s as dates,f as parseDate,p as shift};

package/dist/builtin/date/shift.d.ts

@@ -1,4 +1,4 @@
-export type Unit = "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years";
+export type Unit = "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years" | "weekdays";
 /** Parses an ISO instant, or says which argument was not one. */
 export declare function parseDate(value: string, label: string): Date;
 /** Moves an instant by a whole number of units. Negative goes backwards. */

package/dist/builtin/date/shift.js

@@ -1,47 +1 @@
-const MS = {
-    seconds: 1000,
-    minutes: 60_000,
-    hours: 3_600_000,
-    days: 86_400_000,
-    weeks: 604_800_000,
-};
-export function parseDate(value, label) {
-    const at = new Date(value);
-    if (!Number.isFinite(at.getTime())) {
-        throw new Error(`${label} "${value}" is not a date. Use an ISO instant, as in 2026-03-31.`);
-    }
-    return at;
-}
-function addMonths(from, months) {
-    const day = from.getUTCDate();
-    const shifted = new Date(from.getTime());
-    shifted.setUTCDate(1);
-    shifted.setUTCMonth(shifted.getUTCMonth() + months);
-    const lastOfMonth = new Date(Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth() + 1, 0)).getUTCDate();
-    shifted.setUTCDate(Math.min(day, lastOfMonth));
-    return shifted;
-}
-export function shift(from, amount, unit) {
-    if (!Number.isInteger(amount))
-        throw new Error("amount must be a whole number.");
-    if (unit === "months")
-        return addMonths(from, amount);
-    if (unit === "years")
-        return addMonths(from, amount * 12);
-    const ms = MS[unit];
-    if (!ms)
-        throw new Error(`"${unit}" is not a unit this tool knows.`);
-    return new Date(from.getTime() + amount * ms);
-}
-export function between(from, to, unit) {
-    if (unit === "months" || unit === "years") {
-        const months = (to.getUTCFullYear() - from.getUTCFullYear()) * 12 +
-            (to.getUTCMonth() - from.getUTCMonth()) -
-            (to.getUTCDate() < from.getUTCDate() ? 1 : 0);
-        return unit === "years" ? Math.trunc(months / 12) : months;
-    }
-    const ms = MS[unit];
-    if (!ms)
-        throw new Error(`"${unit}" is not a unit this tool knows.`);
-    return Math.trunc((to.getTime() - from.getTime()) / ms);
-}
+const T={seconds:1e3,minutes:6e4,hours:36e5,days:864e5,weeks:6048e5};function D(e,t){const n=new Date(e);if(!Number.isFinite(n.getTime()))throw new Error(`${t} "${e}" is not a date. Use an ISO instant, as in 2026-03-31.`);return n}function w(e,t){const n=e.getUTCDate(),s=new Date(e.getTime());s.setUTCDate(1),s.setUTCMonth(s.getUTCMonth()+t);const a=new Date(Date.UTC(s.getUTCFullYear(),s.getUTCMonth()+1,0)).getUTCDate();return s.setUTCDate(Math.min(n,a)),s}const i=864e5,g=e=>e.getUTCDay()===0||e.getUTCDay()===6;function h(e,t){const n=t<0?-i:i;let s=new Date(e.getTime()),a=Math.abs(t);for(;a>0;)s=new Date(s.getTime()+n),g(s)||(a-=1);return s}function l(e,t,n){if(!Number.isInteger(t))throw new Error("amount must be a whole number.");if(n==="months")return w(e,t);if(n==="years")return w(e,t*12);if(n==="weekdays")return h(e,t);const s=T[n];if(!s)throw new Error(`"${n}" is not a unit this tool knows.`);return new Date(e.getTime()+t*s)}function U(e,t,n){if(n==="months"||n==="years"){const a=(t.getUTCFullYear()-e.getUTCFullYear())*12+(t.getUTCMonth()-e.getUTCMonth())-(t.getUTCDate()<e.getUTCDate()?1:0);return n==="years"?Math.trunc(a/12):a}if(n==="weekdays")return c(e,t);const s=T[n];if(!s)throw new Error(`"${n}" is not a unit this tool knows.`);return Math.trunc((t.getTime()-e.getTime())/s)}function c(e,t){const n=t.getTime()<e.getTime(),[s,a]=n?[t,e]:[e,t];let o=0,r=new Date(s.getTime());for(;r.getTime()+i<=a.getTime();)r=new Date(r.getTime()+i),g(r)||(o+=1);return n?-o:o}export{U as between,D as parseDate,l as shift};

package/dist/builtin/date/words.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `date_math` asked in words, for a caller that can only send a question.
+ *
+ * Three forms are read — a span between two dates, and a date moved forward
+ * or back — with dates as ISO. Anything else is refused with the forms named,
+ * so a miss is recorded rather than a date guessed at.
+ */
+export declare function dates(): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 2000;
+}]>>;

package/dist/builtin/date/words.js

@@ -0,0 +1 @@
+import{tool as f}from"../../tool/index.js";import{dateMath as h}from"./date.js";const a=String.raw`(\d{4}-\d{2}-\d{2}(?:T[\d:.]+Z?)?)`,m=String.raw`(-?\d+(?:\.\d+)?)`,r=String.raw`(seconds?|minutes?|hours?|days?|weeks?|months?|years?)`,w=new RegExp(`${r}\\s+(?:from|between)\\s+${a}\\s+(?:to|and)\\s+${a}`,"i"),p=new RegExp(`${m}\\s+${r}\\s+after\\s+${a}`,"i"),E=new RegExp(`${m}\\s+${r}\\s+before\\s+${a}`,"i"),u="'days from 2026-03-01 to 2026-09-09', '30 days after 2026-03-01', or '2 months before 2026-03-01'",i=t=>(t.endsWith("s")?t:`${t}s`).toLowerCase();function $(t){const o=t.match(w);if(o){const[,e,n,s]=o;return{operation:"difference",unit:i(e),date:n,to:s}}const d=t.match(p);if(d){const[,e,n,s]=d;return{operation:"add",amount:Number(e),unit:i(n),date:s}}const c=t.match(E);if(c){const[,e,n,s]=c;return{operation:"subtract",amount:Number(e),unit:i(n),date:s}}throw new Error(`Ask date_math as one of ${u}, with dates as YYYY-MM-DD.`)}function b(){const t=h();return f({name:"date_math",description:`Date arithmetic, exact: how far apart two dates are, or a date moved by an amount. Ask as ${u}. Units: seconds, minutes, hours, days, weeks, months, years.`,effect:"readonly",args:[{name:"question",type:"string",required:!0,maxLength:2e3}],run:({question:o})=>t.run($(o))})}export{b as dates};

package/dist/builtin/decline/decline.d.ts

@@ -0,0 +1,49 @@
+import type { ToolResult } from "../../types/index.js";
+/** Why an answer was not given. */
+export type Unanswerable = "unknowable" | "not_covered" | "out_of_scope" | "unsafe";
+/** What `decline` returns, so a loop can tell it from an answer. */
+export interface Declined {
+    declined: true;
+    because: Unanswerable;
+    reason: string;
+}
+/**
+ * True when this result is the model saying it will not answer.
+ *
+ * The counterpart to `isFinished`. Both end a run and they are opposite
+ * outcomes, so a caller that reads only "the loop finished" cannot tell a
+ * question answered from a question refused — and a refusal recorded as an
+ * answer is a support queue that looks healthy and a customer who got nothing.
+ */
+export declare function isDeclined(result: ToolResult): boolean;
+/** Reads the refusal out of a result, or null if it is not one. */
+export declare function declinedFor(result: ToolResult): Declined | null;
+/**
+ * Say the question cannot be answered, rather than answering it anyway.
+ *
+ * The third thing an agent can do, beside answering and asking. Asking only
+ * helps where the missing piece is the person's to supply: "which subscription"
+ * has an answer they know, and "what will the base rate be next March" has no
+ * answer anybody knows. A model with only `finish` and a clarifying question
+ * handles the second by guessing or by asking something that cannot help.
+ *
+ * `because` is a small fixed set rather than free text, so the rate of each is
+ * countable. `unknowable` and `not_covered` want opposite fixes — one is the
+ * world, the other is your records — and a single "declined" number cannot tell
+ * you which you have.
+ *
+ * Pinned for the reason `finish` is: it is how a run ends, not a tool competing
+ * to be relevant, and a turn whose shortlist dropped it has no way to say no.
+ */
+export declare function decline(): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "because";
+    readonly type: "enum";
+    readonly required: true;
+    readonly options: Unanswerable[];
+}, {
+    readonly name: "reason";
+    readonly type: "text";
+    readonly required: true;
+    readonly maxLength: 2000;
+    readonly description: "One sentence the person who asked can read.";
+}]>>;

package/dist/builtin/decline/decline.js

@@ -0,0 +1 @@
+import{tool as t}from"../../tool/index.js";const o=["unknowable","not_covered","out_of_scope","unsafe"];function r(e){if(e.name!=="decline"||e.status!=="completed")return!1;try{return JSON.parse(e.output).declined===!0}catch{return!1}}function u(e){return r(e)?JSON.parse(e.output):null}function i(){return t({name:"decline",effect:"readonly",pinned:!0,description:"Call this when the question cannot be answered: nobody knows (unknowable), your records do not cover it (not_covered), it is not what you are for (out_of_scope), or answering would be unsafe. Use it instead of guessing. If the person could supply what is missing, ask them instead.",args:[{name:"because",type:"enum",required:!0,options:o},{name:"reason",type:"text",required:!0,maxLength:2e3,description:"One sentence the person who asked can read."}],run:({because:e,reason:n})=>({declined:!0,because:e,reason:n})})}export{i as decline,u as declinedFor,r as isDeclined};

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

@@ -0,0 +1 @@
+export { type Declined, decline, declinedFor, isDeclined, type Unanswerable } from "./decline.js";

package/dist/builtin/decline/index.js

@@ -0,0 +1 @@
+import{decline as i,declinedFor as c,isDeclined as l}from"./decline.js";export{i as decline,c as declinedFor,l as isDeclined};

package/dist/builtin/escalate/escalate.d.ts

@@ -1,3 +1,4 @@
+import type { ToolResult } from "../../types/index.js";
 export interface EscalateOptions {
     /**
      * What actually happens — page someone, open a ticket, write to a queue.
@@ -19,6 +20,24 @@ export interface EscalationRequest {
     summary?: string;
     urgency: "low" | "normal" | "high";
 }
+/** What `escalate` returns, so a run can be read back for whether a person was told. */
+export interface Escalated {
+    escalated: true;
+    /** False when nothing was wired to receive it, or the handler was not reached. */
+    delivered: boolean;
+    request: EscalationRequest;
+    handled?: unknown;
+}
+/**
+ * True when this result is the model handing the work to a person.
+ *
+ * The counterpart to `isFinished`. A run that called `escalate` and a run that
+ * escalated are not the same thing — the call can fail, and telling a customer
+ * they have been passed on when nobody was told is the worse half of the two.
+ */
+export declare function isEscalated(result: ToolResult): boolean;
+/** Reads the request out of an escalated result, or null if it is not one. */
+export declare function escalationOf(result: ToolResult): Escalated | null;
 /**
  * Hand back to a person rather than guess.
  *

package/dist/builtin/escalate/escalate.js

@@ -1,20 +1 @@
-import { tool } from "../../tool/index.js";
-export function escalate(opts = {}) {
-    return tool({
-        name: "escalate",
-        description: "Hand this over to a person. Call it when you are missing something you cannot " +
-            "get, when the request needs an authority you do not have, or when acting on a " +
-            "guess would be worse than waiting. Say plainly why.",
-        pinned: opts.pinned ?? true,
-        args: [
-            { name: "reason", type: "text", required: true, maxLength: 2000 },
-            { name: "summary", type: "text", required: false, maxLength: 4000 },
-            { name: "urgency", type: "enum", required: false, options: ["low", "normal", "high"] },
-        ],
-        run: async ({ reason, summary, urgency = "normal" }) => {
-            const request = { reason, summary, urgency };
-            const handled = opts.onEscalate ? await opts.onEscalate(request) : undefined;
-            return { escalated: true, delivered: Boolean(opts.onEscalate), request, handled };
-        },
-    });
-}
+import{tool as u}from"../../tool/index.js";function s(e){if(e.name!=="escalate"||e.status!=="completed")return!1;try{return JSON.parse(e.output).escalated===!0}catch{return!1}}function l(e){return s(e)?JSON.parse(e.output):null}function c(e={}){return u({name:"escalate",description:"Hand this over to a person. Call it when you are missing something you cannot get, when the request needs an authority you do not have, or when acting on a guess would be worse than waiting. Say plainly why.",pinned:e.pinned??!0,args:[{name:"reason",type:"text",required:!0,maxLength:2e3},{name:"summary",type:"text",required:!1,maxLength:4e3},{name:"urgency",type:"enum",required:!1,options:["low","normal","high"]}],run:async({reason:t,summary:a,urgency:r="normal"})=>{const n={reason:t,summary:a,urgency:r},o=e.onEscalate?await e.onEscalate(n):void 0;return{escalated:!0,delivered:!!e.onEscalate,request:n,handled:o}}})}export{c as escalate,l as escalationOf,s as isEscalated};

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

@@ -1 +1 @@
-export { type EscalateOptions, type EscalationRequest, escalate } from "./escalate.js";
+export { type Escalated, type EscalateOptions, type EscalationRequest, escalate, escalationOf, isEscalated, } from "./escalate.js";

package/dist/builtin/escalate/index.js

@@ -1 +1 @@
-export { escalate } from "./escalate.js";
+import{escalate as s,escalationOf as t,isEscalated as c}from"./escalate.js";export{s as escalate,t as escalationOf,c as isEscalated};

package/dist/builtin/extract/extract.d.ts

@@ -0,0 +1,25 @@
+export interface ExtractOptions {
+    /** Hosts a file may be read from. Default any public https host. */
+    allow?: string[];
+    /** Longest text handed back. Default 20000 characters. */
+    maxChars?: number;
+    /** Largest file read. Default 20 MB. */
+    maxBytes?: number;
+    /** Give up after this. Default 20000. */
+    timeoutMs?: number;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * The text of a file at a URL — a PDF, a Word document, a page, or plain
+ * text — so a model can read what a link points at instead of guessing.
+ *
+ * The same guard as `http_request`: https only, no private addresses, and an
+ * allowlist you choose. Nothing is stored.
+ */
+export declare function extract(opts?: ExtractOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "url";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 2000;
+}]>>;

package/dist/builtin/extract/extract.js

@@ -0,0 +1 @@
+import{tool as u}from"../../tool/index.js";import{ANY_HOST as w,checkUrl as y}from"../http/allow.js";import{followChecked as g}from"../http/hops.js";import{KINDS as x,kindOf as b,nameOf as l}from"./kinds.js";import{read as E}from"./readers.js";const T=2e4,_=20*1024*1024,p=2e4;function M(t={}){const o=t.allow?.length?t.allow:[w],m=t.fetch??globalThis.fetch.bind(globalThis),i=t.maxChars??T,s=t.maxBytes??_;return u({name:"extract",effect:"readonly",trust:"external",description:"Reads the file at a URL and returns its text: a PDF, a Word document (.docx), a web page, Markdown or plain text. Use it when a finding or a person hands you a link and you need what is actually on it, not a summary of it.",args:[{name:"url",type:"string",required:!0,maxLength:2e3}],run:async({url:d})=>{const e=y(d,o),h=AbortSignal.timeout(t.timeoutMs??p),r=await g(f=>m(f,{signal:h,redirect:"manual"}),e,o);if(!r.ok)throw new Error(`${e.hostname} answered ${r.status}.`);const c=b(r.headers.get("content-type"),e);if(!c)throw new Error(`Cannot read ${l(e)}: not one of ${x.join(", ")}, by type or by name.`);const n=await r.arrayBuffer();if(n.byteLength>s)throw new Error(`${l(e)} is ${n.byteLength} bytes, over the ${s} read.`);const a=await E(c,n);return a.length>i?`${a.slice(0,i).trimEnd()}\u2026`:a}})}export{M as extract};

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

@@ -0,0 +1,3 @@
+export { type ExtractOptions, extract } from "./extract.js";
+export { KINDS, type Kind, kindOf, nameOf } from "./kinds.js";
+export { fromDocx, fromHtml, fromPdf, read } from "./readers.js";

package/dist/builtin/extract/index.js

@@ -0,0 +1 @@
+import{extract as f}from"./extract.js";import{KINDS as e,kindOf as t,nameOf as x}from"./kinds.js";import{fromDocx as d,fromHtml as p,fromPdf as c,read as n}from"./readers.js";export{e as KINDS,f as extract,d as fromDocx,p as fromHtml,c as fromPdf,t as kindOf,x as nameOf,n as read};

package/dist/builtin/extract/kinds.d.ts

@@ -0,0 +1,6 @@
+export declare const KINDS: readonly ["pdf", "docx", "html", "md", "txt"];
+export type Kind = (typeof KINDS)[number];
+/** What a file is: its declared type first, the URL's extension when the type says nothing. */
+export declare function kindOf(contentType: string | null, url: URL): Kind | null;
+/** The name the file goes by, from the last path segment, or the host when there is none. */
+export declare function nameOf(url: URL): string;

package/dist/builtin/extract/kinds.js

@@ -0,0 +1 @@
+const a=["pdf","docx","html","md","txt"],p=[["application/pdf","pdf"],["application/vnd.openxmlformats-officedocument.wordprocessingml.document","docx"],["text/html","html"],["application/xhtml+xml","html"],["text/markdown","md"],["text/x-markdown","md"],["text/plain","txt"]],l={pdf:"pdf",docx:"docx",html:"html",htm:"html",md:"md",markdown:"md",txt:"txt",text:"txt"};function c(t,o){const e=(t??"").split(";")[0]?.trim().toLowerCase()??"",n=p.find(([d])=>d===e)?.[1];if(n)return n;const m=o.pathname.split(".").pop()?.toLowerCase()??"";return l[m]??null}function x(t){const o=t.pathname.split("/").filter(Boolean).pop();return o?decodeURIComponent(o):t.hostname}export{a as KINDS,c as kindOf,x as nameOf};

package/dist/builtin/extract/readers.d.ts

@@ -0,0 +1,7 @@
+import type { Kind } from "./kinds.js";
+/** The words in a page: scripts and styles gone, block ends become breaks, tags dropped. */
+export declare function fromHtml(html: string): string;
+/** The words in a Word document: each paragraph in `word/document.xml`, in order. */
+export declare function fromDocx(bytes: ArrayBuffer): Promise<string>;
+export declare function fromPdf(bytes: ArrayBuffer): Promise<string>;
+export declare function read(kind: Kind, bytes: ArrayBuffer): Promise<string>;

package/dist/builtin/extract/readers.js

@@ -0,0 +1,9 @@
+import p from"jszip";import{extractText as m}from"unpdf";const u={amp:"&",lt:"<",gt:">",quot:'"',apos:"'",nbsp:" "};function o(t){return t.replace(/&(#\d+|#x[0-9a-f]+|[a-z]+);/gi,(r,e)=>e.startsWith("#x")?String.fromCodePoint(Number.parseInt(e.slice(2),16)):e.startsWith("#")?String.fromCodePoint(Number(e.slice(1))):u[e.toLowerCase()]??r)}function n(t){return t.replace(/[ \t]+\n/g,`
+`).replace(/\n{3,}/g,`
+
+`).trim()}function l(t){const r=t.replace(/<(script|style)\b[\s\S]*?<\/\1>/gi,"").replace(/<br\s*\/?>/gi,`
+`).replace(/<\/(p|div|h[1-6]|li|tr|blockquote|pre|section|article|header|footer)>/gi,`
+
+`).replace(/<[^>]+>/g,"");return n(o(r))}async function d(t){const e=(await p.loadAsync(t)).file("word/document.xml");if(!e)throw new Error("This is not a Word document: it has no word/document.xml.");const c=[...(await e.async("string")).matchAll(/<w:p\b[\s\S]*?<\/w:p>/g)].map(i=>[...i[0].matchAll(/<w:t\b[^>]*>([\s\S]*?)<\/w:t>/g)].map(s=>s[1]??"").join(""));return n(c.map(o).join(`
+
+`))}async function f(t){const{text:r}=await m(new Uint8Array(t),{mergePages:!0});return n(r)}const a=new TextDecoder;async function h(t,r){switch(t){case"pdf":return f(r);case"docx":return d(r);case"html":return l(a.decode(r));default:return n(a.decode(r))}}export{d as fromDocx,l as fromHtml,f as fromPdf,h as read};

package/dist/builtin/finish/finish.d.ts

@@ -18,6 +18,10 @@ export declare function answerOf(result: ToolResult): string | null;
  *
  * Without it a loop ends by the model going quiet, which is indistinguishable
  * from it losing the thread.
+ *
+ * Pinned, so a shortlist cannot drop it. It is not a tool competing to be
+ * relevant to the question — it is how the loop is told to stop, and a turn
+ * offered four tools that are not this one has no way to say it is done.
  */
 export declare function finish(): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
     readonly name: "answer";

package/dist/builtin/finish/finish.js

@@ -1,26 +1 @@
-import { tool } from "../../tool/index.js";
-export function isFinished(result) {
-    if (result.name !== "finish" || result.status !== "completed")
-        return false;
-    try {
-        return JSON.parse(result.output).done === true;
-    }
-    catch {
-        return false;
-    }
-}
-export function answerOf(result) {
-    if (!isFinished(result))
-        return null;
-    return JSON.parse(result.output).answer;
-}
-export function finish() {
-    return tool({
-        name: "finish",
-        effect: "readonly",
-        description: "Call this when you have the answer and need no more tools. Pass the final " +
-            "answer as it should be given to the person who asked.",
-        args: [{ name: "answer", type: "text", required: true, maxLength: 20_000 }],
-        run: ({ answer }) => ({ done: true, answer }),
-    });
-}
+import{tool as n}from"../../tool/index.js";function t(e){if(e.name!=="finish"||e.status!=="completed")return!1;try{return JSON.parse(e.output).done===!0}catch{return!1}}function o(e){return t(e)?JSON.parse(e.output).answer:null}function a(){return n({name:"finish",effect:"readonly",pinned:!0,description:"Call this when you have the answer and need no more tools. Pass the final answer as it should be given to the person who asked.",args:[{name:"answer",type:"text",required:!0,maxLength:2e4}],run:({answer:e})=>({done:!0,answer:e})})}export{o as answerOf,a as finish,t as isFinished};

package/dist/builtin/finish/index.js

@@ -1 +1 @@
-export { answerOf, finish, isFinished } from "./finish.js";
+import{answerOf as e,finish as f,isFinished as n}from"./finish.js";export{e as answerOf,f as finish,n as isFinished};

package/dist/builtin/http/allow.d.ts

@@ -1,3 +1,5 @@
+/** Any public host at all; https and the private-address refusals still apply. */
+export declare const ANY_HOST = "*";
 /**
  * The URL a request may go to, or the reason it may not.
  *

package/dist/builtin/http/allow.js

@@ -1,37 +1 @@
-const PRIVATE_V4 = /^(10\.|127\.|0\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/;
-const LOCAL_NAMES = new Set(["localhost", "metadata.google.internal"]);
-function isPrivateHost(host) {
-    const name = host.toLowerCase();
-    if (LOCAL_NAMES.has(name))
-        return true;
-    if (name.endsWith(".local") || name.endsWith(".internal") || name.endsWith(".localhost")) {
-        return true;
-    }
-    if (name.startsWith("["))
-        return true;
-    return PRIVATE_V4.test(name);
-}
-function matches(host, rule) {
-    const h = host.toLowerCase();
-    const r = rule.toLowerCase();
-    return r.startsWith(".") ? h === r.slice(1) || h.endsWith(r) : h === r;
-}
-export function checkUrl(raw, allow) {
-    let url;
-    try {
-        url = new URL(raw);
-    }
-    catch {
-        throw new Error(`"${raw}" is not a URL.`);
-    }
-    if (url.protocol !== "https:") {
-        throw new Error(`Only https is allowed, and this is ${url.protocol.replace(":", "")}.`);
-    }
-    if (isPrivateHost(url.hostname)) {
-        throw new Error(`${url.hostname} is a private or link-local address.`);
-    }
-    if (!allow.some((rule) => matches(url.hostname, rule))) {
-        throw new Error(`${url.hostname} is not in the allowlist: ${allow.join(", ")}.`);
-    }
-    return url;
-}
+const n=/^(10\.|127\.|0\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/,s=new Set(["localhost","metadata.google.internal"]);function i(e){const t=e.toLowerCase();return s.has(t)||t.endsWith(".local")||t.endsWith(".internal")||t.endsWith(".localhost")||t.startsWith("[")?!0:n.test(t)}const a="*";function h(e,t){if(t===a)return!0;const r=e.toLowerCase(),o=t.toLowerCase();return o.startsWith(".")?r===o.slice(1)||r.endsWith(o):r===o}function c(e,t){let r;try{r=new URL(e)}catch{throw new Error(`"${e}" is not a URL.`)}if(r.protocol!=="https:")throw new Error(`Only https is allowed, and this is ${r.protocol.replace(":","")}.`);if(i(r.hostname))throw new Error(`${r.hostname} is a private or link-local address.`);if(!t.some(o=>h(r.hostname,o)))throw new Error(`${r.hostname} is not in the allowlist: ${t.join(", ")}.`);return r}export{a as ANY_HOST,c as checkUrl};

package/dist/builtin/http/hops.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The response, with every hop checked against the allowlist rather than only
+ * the URL the model named.
+ *
+ * Followed automatically, an allowlisted host answering `302 Location: …` sends
+ * the request anywhere it likes — a private address, a metadata endpoint — and
+ * carries any configured header with it. `send` must therefore pass
+ * `redirect: "manual"`.
+ */
+export declare function followChecked(send: (to: URL) => Promise<Response>, target: URL, allow: string[]): Promise<Response>;

package/dist/builtin/http/hops.js

@@ -0,0 +1 @@
+import{checkUrl as s}from"./allow.js";const a=3,c=e=>e.status>=300&&e.status<400;async function l(e,o,i){let t=await e(o);for(let r=0;r<a&&c(t);r++){const n=t.headers.get("location");if(!n)break;t=await e(s(new URL(n,t.url||o).toString(),i))}if(c(t))throw new Error(`Gave up after ${a} redirects from ${o.hostname}.`);return t}export{l as followChecked};

package/dist/builtin/http/http.d.ts

@@ -3,7 +3,8 @@ export interface HttpOptions {
      * Hosts this tool may reach. Required, and there is no default.
      *
      * `"api.example.com"` matches that host; `".example.com"` matches it and any
-     * subdomain.
+     * subdomain; `"*"` matches every public host, and is the choice to make only
+     * when the tool is a reader of the open web rather than a client of your APIs.
      */
     allow: string[];
     /** Sent on every request — an API key belongs here, never in the args. */
@@ -14,6 +15,8 @@ export interface HttpOptions {
     maxChars?: number;
     /** Injected for tests. */
     fetch?: typeof fetch;
+    /** Injected for tests, for reading a `Retry-After` given as a date. */
+    now?: () => number;
 }
 /**
  * An HTTP GET or POST, to hosts you named.
@@ -24,6 +27,11 @@ export interface HttpOptions {
  *
  * Its `effect` is left unset on purpose: a GET is readonly and a POST to your
  * allowlist may be anything at all, and one label cannot be true of both.
+ *
+ * It makes one request and never retries. Retrying is the caller's, because
+ * only the caller knows whether the call is safe to repeat — and the one thing
+ * a caller needs to retry well, `retryAfterMs`, is handed back rather than
+ * discarded with the rest of the headers.
  */
 export declare function httpRequest(opts: HttpOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
     readonly name: "url";

package/dist/builtin/http/http.js

@@ -1,41 +1 @@
-import { tool } from "../../tool/index.js";
-import { checkUrl } from "./allow.js";
-const DEFAULT_TIMEOUT_MS = 10_000;
-const DEFAULT_MAX_CHARS = 100_000;
-export function httpRequest(opts) {
-    if (!opts.allow?.length) {
-        throw new Error("httpRequest needs an allow list of hosts; there is no safe default.");
-    }
-    const doFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
-    const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
-    return tool({
-        name: "http_request",
-        description: `Fetches a URL and returns its status and body. Only these hosts are reachable: ` +
-            `${opts.allow.join(", ")}. Use it to read an API or a page you have been pointed at.`,
-        args: [
-            { name: "url", type: "string", required: true, maxLength: 2000 },
-            { name: "method", type: "enum", required: false, options: ["GET", "POST"] },
-            { name: "body", type: "text", required: false, maxLength: 20_000 },
-        ],
-        run: async ({ url, method = "GET", body }) => {
-            const target = checkUrl(url, opts.allow);
-            const signal = AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-            const res = await doFetch(target, {
-                method,
-                signal,
-                headers: {
-                    ...opts.headers,
-                    ...(body ? { "content-type": "application/json" } : {}),
-                },
-                ...(body && method === "POST" ? { body } : {}),
-            });
-            const text = await res.text();
-            return {
-                status: res.status,
-                ok: res.ok,
-                body: text.slice(0, maxChars),
-                truncated: text.length > maxChars,
-            };
-        },
-    });
-}
+import{tool as d}from"../../tool/index.js";import{ANY_HOST as m,checkUrl as f}from"./allow.js";import{followChecked as g}from"./hops.js";import{retryAfterMs as p}from"./retry-after.js";const y=1e4,w=1e5;function T(e){return e.includes(m)?"Any public https host is reachable.":`Only these hosts are reachable: ${e.join(", ")}.`}function q(e){if(!e.allow?.length)throw new Error("httpRequest needs an allow list of hosts; there is no safe default.");const i=e.fetch??globalThis.fetch.bind(globalThis),a=e.maxChars??w;return d({name:"http_request",description:`Fetches a URL and returns its status and body. ${T(e.allow)} Use it to read an API or a page you have been pointed at.`,args:[{name:"url",type:"string",required:!0,maxLength:2e3},{name:"method",type:"enum",required:!1,options:["GET","POST"]},{name:"body",type:"text",required:!1,maxLength:2e4}],run:async({url:l,method:n="GET",body:r})=>{const c=f(l,e.allow),h=AbortSignal.timeout(e.timeoutMs??y),t=await g(u=>i(u,{method:n,signal:h,redirect:"manual",headers:{...e.headers,...r?{"content-type":"application/json"}:{}},...r&&n==="POST"?{body:r}:{}}),c,e.allow),s=await t.text(),o=p(t.headers.get("retry-after"),e.now);return{status:t.status,ok:t.ok,body:s.slice(0,a),truncated:s.length>a,...o===null?{}:{retryAfterMs:o}}}})}export{q as httpRequest};

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

@@ -1,2 +1,4 @@
 export { checkUrl } from "./allow.js";
+export { followChecked } from "./hops.js";
 export { type HttpOptions, httpRequest } from "./http.js";
+export { retryAfterMs } from "./retry-after.js";

package/dist/builtin/http/index.js

@@ -1,2 +1 @@
-export { checkUrl } from "./allow.js";
-export { httpRequest } from "./http.js";
+import{checkUrl as o}from"./allow.js";import{followChecked as f}from"./hops.js";import{httpRequest as m}from"./http.js";import{retryAfterMs as c}from"./retry-after.js";export{o as checkUrl,f as followChecked,m as httpRequest,c as retryAfterMs};

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

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

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

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

package/dist/builtin/index.d.ts

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

package/dist/builtin/index.js

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

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

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

package/dist/builtin/json/index.js

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