@spendgraph/tools 0.4.0 → 0.6.0

package/dist/bogus/my-calendar.js

@@ -0,0 +1 @@
+import{tool as n}from"../tool/index.js";import{receipt as d}from"./receipt.js";const a={today:["09:30 standup","13:00 lunch with Rafi","19:00 futsal"],tomorrow:["11:00 dentist \u2014 the one you already moved twice"],saturday:[]};function y(){return n({name:"my_calendar",effect:"readonly",description:"What is on the user's calendar for a given day.",args:[{name:"question",type:"string",required:!1,description:"Names a day \u2014 today, tomorrow, or saturday. Defaults to today."}],run:({question:o="today"})=>{const e=Object.keys(a).find(r=>o.toLowerCase().includes(r))??"today",t=a[e]??[];return{day:e,events:t,free:t.length===0,receipt:d("my_calendar",e)}}})}export{y as myCalendar};

package/dist/bogus/my-notes.d.ts

@@ -0,0 +1,6 @@
+export declare function myNotes(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly description: "What to look for.";
+}]>>;

package/dist/bogus/my-notes.js

@@ -0,0 +1 @@
+import{tool as s}from"../tool/index.js";import{receipt as r}from"./receipt.js";const t={workout:"PPL, 4 days. Push Mon, Pull Wed, Legs Fri, Rest Sun.",wifi:"Router password is on the fridge. Nobody knows the admin one.",passport:"Renewal needs the old passport, NID, and a 5,000 BDT fee.",landlord:"Rent is due on the 5th. He does not accept bKash. He will insist he does."};function d(){return s({name:"my_notes",effect:"readonly",description:"Search the user's own notes. Only place their personal facts live \u2014 passwords, plans, things they wrote down so they would not have to remember them.",args:[{name:"question",type:"string",required:!0,description:"What to look for."}],run:({question:o})=>{const e=Object.keys(t).find(n=>o.toLowerCase().includes(n));return e?{found:!0,note:t[e],written:"2026-08-01",receipt:r("my_notes",e)}:{found:!1,note:null,searched:o}}})}export{d as myNotes};

package/dist/bogus/my-recipes.d.ts

@@ -0,0 +1,6 @@
+export declare function myRecipes(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly description: "Names a dish.";
+}]>>;

package/dist/bogus/my-recipes.js

@@ -0,0 +1 @@
+import{tool as i}from"../tool/index.js";import{receipt as s}from"./receipt.js";const o={khichuri:"Rice, moong dal, ginger, whole spices. 1:1 rice to dal. Do not stir it to death.",omelette:"Three eggs, one onion, one green chilli. Butter, not oil. 90 seconds a side.",tea:"Boil water. Add tea. Add milk. Argue about the order for twenty minutes."};function a(){return i({name:"my_recipes",effect:"readonly",description:"The user's saved recipes. Not a cookbook \u2014 only what they saved themselves.",args:[{name:"question",type:"string",required:!0,description:"Names a dish."}],run:({question:t})=>{const e=Object.keys(o).find(r=>t.toLowerCase().includes(r));return e?{found:!0,dish:e,method:o[e],receipt:s("my_recipes",e)}:{found:!1,dish:null,asked:t}}})}export{a as myRecipes};

package/dist/bogus/order-pizza.d.ts

@@ -0,0 +1,12 @@
+export declare function orderPizza(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "pizza";
+    readonly type: "enum";
+    readonly required: true;
+    readonly options: string[];
+}, {
+    readonly name: "quantity";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 1;
+    readonly max: 10;
+}]>>;

package/dist/bogus/order-pizza.js

@@ -0,0 +1 @@
+import{tool as a}from"../tool/index.js";import{receipt as o}from"./receipt.js";const i={margherita:690,pepperoni:890,"beef bulgogi":1090};function d(){return a({name:"order_pizza",effect:"destructive",description:"Places a real pizza order and charges the card on file. There is no undo. A pizza will arrive whether or not it was wanted.",args:[{name:"pizza",type:"enum",required:!0,options:Object.keys(i)},{name:"quantity",type:"number",required:!1,min:1,max:10}],run:({pizza:e,quantity:r=1})=>({ordered:e,quantity:r,bdt:(i[e]??0)*r,arriving:"in 35 minutes",cancellable:!1,receipt:o("order_pizza",`${e}x${r}`)})})}export{d as orderPizza};

package/dist/bogus/prayer-times.d.ts

@@ -0,0 +1,6 @@
+export declare function prayerTimes(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly description: "Names a city.";
+}]>>;

package/dist/bogus/prayer-times.js

@@ -0,0 +1 @@
+import{tool as i}from"../tool/index.js";import{receipt as o}from"./receipt.js";const t={dhaka:{fajr:"04:07",dhuhr:"12:41",asr:"16:03",maghrib:"18:29",isha:"19:53"},chittagong:{fajr:"04:01",dhuhr:"12:37",asr:"15:59",maghrib:"18:23",isha:"19:47"}};function m(){return i({name:"prayer_times",effect:"readonly",description:"Today's times from the Bogus Almanac, for Dhaka or Chittagong. They differ from any published table, so answer from what this returns rather than from memory.",args:[{name:"question",type:"string",required:!0,description:"Names a city."}],run:({question:r})=>{const e=Object.keys(t).find(a=>r.toLowerCase().includes(a));return e?{city:e,date:"2026-09-04",times:t[e],receipt:o("prayer_times",e)}:{asked:r,date:"2026-09-04",times:null,note:"city not covered"}}})}export{m as prayerTimes};

package/dist/bogus/receipt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A token no model could produce without calling the tool.
+ *
+ * Every bogus reply carries one. Grep an answer for `bogus-` and you know which
+ * tools actually reached it — the model cannot invent a receipt it never saw,
+ * so provenance is observed rather than claimed.
+ */
+export declare function receipt(tool: string, key: string): string;

package/dist/bogus/receipt.js

@@ -0,0 +1 @@
+function o(r,e){let t=0;for(const c of`${r}:${e}`)t=t*31+c.charCodeAt(0)>>>0;return`bogus-${r}-${t.toString(16).padStart(8,"0").slice(0,6)}`}export{o as receipt};

package/dist/builtin/calculate/calculate.js

@@ -1,21 +1 @@
-import { tool } from "../../tool/index.js";
-import { evaluate } from "./parse.js";
-export function calculate() {
-    return tool({
-        name: "calculate",
-        effect: "readonly",
-        description: "Works out an arithmetic expression exactly. Use it for any sum that matters — " +
-            "totals, percentages, differences, rates. Supports + - * / % ^, brackets, and " +
-            "sqrt, abs, round, floor, ceil, ln, log.",
-        args: [
-            {
-                name: "expression",
-                type: "string",
-                required: true,
-                maxLength: 500,
-                description: "For example (1250 * 0.2) + 99, or sqrt(144).",
-            },
-        ],
-        run: ({ expression }) => evaluate(expression),
-    });
-}
+import{tool as r}from"../../tool/index.js";import{exact as t}from"./exact.js";import{evaluate as o}from"./parse.js";function i(){return r({name:"calculate",effect:"readonly",description:"Works out an arithmetic expression exactly. Use it for any sum that matters \u2014 totals, percentages, differences, rates. Supports + - * / % ^, brackets, and sqrt, abs, round, floor, ceil, ln, log.",args:[{name:"expression",type:"string",required:!0,maxLength:500,description:"For example (1250 * 0.2) + 99, or sqrt(144)."}],run:({expression:e})=>t(o(e))})}export{i as calculate};

package/dist/builtin/calculate/exact.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A result as the number that was worked out, not as the binary that holds it.
+ *
+ * The tool's own description promises to work an expression out *exactly*, and
+ * `JSON.stringify(0.1 + 0.2)` is `"0.30000000000000004"`. That number goes to
+ * the model, and the model says it to a person — about money, in a repo whose
+ * first rule is that costs are integers because floats do not sum exactly.
+ *
+ * Rounding to the fifteen significant digits a double genuinely carries removes
+ * the artefact and keeps every digit that was real: `0.1 + 0.2` is `0.3`,
+ * `(1.1 - 1) * 10` is `1`, and `1 / 3` is still `0.333333333333333`.
+ *
+ * This is presentation, not arithmetic. It cannot make a float exact; it stops
+ * the tool claiming a precision the double never had.
+ */
+export declare function exact(value: number): string;

package/dist/builtin/calculate/exact.js

@@ -0,0 +1 @@
+const t=15;function n(r){return Number.isInteger(r)?String(r):String(Number.parseFloat(r.toPrecision(15)))}export{n as exact};

package/dist/builtin/calculate/index.js

@@ -1,2 +1 @@
-export { calculate } from "./calculate.js";
-export { evaluate } from "./parse.js";
+import{calculate as o}from"./calculate.js";import{evaluate as t}from"./parse.js";export{o as calculate,t as evaluate};

package/dist/builtin/calculate/parse.js

@@ -1,137 +1 @@
-const FUNCTIONS = {
-    sqrt: Math.sqrt,
-    abs: Math.abs,
-    round: Math.round,
-    floor: Math.floor,
-    ceil: Math.ceil,
-    ln: Math.log,
-    log: Math.log10,
-};
-const OPERATORS = new Set(["+", "-", "*", "/", "%", "^", "(", ")", ","]);
-function tokenize(input) {
-    const tokens = [];
-    let i = 0;
-    while (i < input.length) {
-        const ch = input[i];
-        if (ch === " " || ch === "\t" || ch === "_") {
-            i++;
-            continue;
-        }
-        if (ch >= "0" && ch <= "9") {
-            let j = i;
-            while (j < input.length && /[0-9._]/.test(input[j]))
-                j++;
-            const value = Number(input.slice(i, j).replace(/_/g, ""));
-            if (!Number.isFinite(value))
-                throw new Error(`"${input.slice(i, j)}" is not a number.`);
-            tokens.push({ kind: "number", value });
-            i = j;
-            continue;
-        }
-        if (/[a-z]/i.test(ch)) {
-            let j = i;
-            while (j < input.length && /[a-z]/i.test(input[j]))
-                j++;
-            tokens.push({ kind: "op", value: input.slice(i, j).toLowerCase() });
-            i = j;
-            continue;
-        }
-        if (OPERATORS.has(ch)) {
-            tokens.push({ kind: "op", value: ch });
-            i++;
-            continue;
-        }
-        throw new Error(`"${ch}" is not something this calculator understands.`);
-    }
-    return tokens;
-}
-class Reader {
-    tokens;
-    at = 0;
-    constructor(tokens) {
-        this.tokens = tokens;
-    }
-    peek() {
-        return this.tokens[this.at];
-    }
-    take() {
-        return this.tokens[this.at++];
-    }
-    eat(value) {
-        const next = this.peek();
-        if (next?.kind === "op" && next.value === value) {
-            this.at++;
-            return true;
-        }
-        return false;
-    }
-    get done() {
-        return this.at >= this.tokens.length;
-    }
-}
-function primary(r) {
-    const token = r.take();
-    if (!token)
-        throw new Error("The expression ends where a number was expected.");
-    if (token.kind === "number")
-        return token.value;
-    if (token.value === "-")
-        return -primary(r);
-    if (token.value === "+")
-        return primary(r);
-    if (token.value === "(") {
-        const value = additive(r);
-        if (!r.eat(")"))
-            throw new Error("A bracket was opened and never closed.");
-        return value;
-    }
-    const fn = FUNCTIONS[token.value];
-    if (!fn)
-        throw new Error(`"${token.value}" is not a function this calculator has.`);
-    if (!r.eat("("))
-        throw new Error(`${token.value} needs brackets, as in ${token.value}(9).`);
-    const arg = additive(r);
-    if (!r.eat(")"))
-        throw new Error("A bracket was opened and never closed.");
-    return fn(arg);
-}
-function power(r) {
-    const base = primary(r);
-    if (r.eat("^"))
-        return base ** power(r);
-    return base;
-}
-function multiplicative(r) {
-    let value = power(r);
-    for (;;) {
-        if (r.eat("*"))
-            value *= power(r);
-        else if (r.eat("/"))
-            value /= power(r);
-        else if (r.eat("%"))
-            value %= power(r);
-        else
-            return value;
-    }
-}
-function additive(r) {
-    let value = multiplicative(r);
-    for (;;) {
-        if (r.eat("+"))
-            value += multiplicative(r);
-        else if (r.eat("-"))
-            value -= multiplicative(r);
-        else
-            return value;
-    }
-}
-export function evaluate(expression) {
-    const reader = new Reader(tokenize(expression));
-    const value = additive(reader);
-    if (!reader.done)
-        throw new Error("There is something left over after the expression.");
-    if (!Number.isFinite(value)) {
-        throw new Error(value === Infinity || value === -Infinity ? "That divides by zero." : "That is not a number.");
-    }
-    return value;
-}
+const l={sqrt:Math.sqrt,abs:Math.abs,round:Math.round,floor:Math.floor,ceil:Math.ceil,ln:Math.log,log:Math.log10},h=new Set(["+","-","*","/","%","^","(",")",","]);function c(e){const t=Number(e.replace(/_/g,""));if(!Number.isFinite(t))throw new Error(`"${e}" is not a number.`);if(!e.includes(".")&&!Number.isSafeInteger(t))throw new Error(`${e} is too large for this calculator to hold exactly. Whole numbers up to 9007199254740991 are safe.`);return t}function f(e){const t=[];let n=0;for(;n<e.length;){const o=e[n];if(o===" "||o==="	"||o==="_"){n++;continue}if(o>="0"&&o<="9"){let r=n;for(;r<e.length&&/[0-9._]/.test(e[r]);)r++;t.push({kind:"number",value:c(e.slice(n,r))}),n=r;continue}if(/[a-z]/i.test(o)){let r=n;for(;r<e.length&&/[a-z]/i.test(e[r]);)r++;t.push({kind:"op",value:e.slice(n,r).toLowerCase()}),n=r;continue}if(h.has(o)){t.push({kind:"op",value:o}),n++;continue}throw new Error(`"${o}" is not something this calculator understands.`)}return t}class w{tokens;at=0;constructor(t){this.tokens=t}peek(){return this.tokens[this.at]}take(){return this.tokens[this.at++]}eat(t){const n=this.peek();return n?.kind==="op"&&n.value===t?(this.at++,!0):!1}get done(){return this.at>=this.tokens.length}}function s(e){const t=e.take();if(!t)throw new Error("The expression ends where a number was expected.");if(t.kind==="number")return t.value;if(t.value==="-")return-s(e);if(t.value==="+")return s(e);if(t.value==="("){const r=u(e);if(!e.eat(")"))throw new Error("A bracket was opened and never closed.");return r}const n=l[t.value];if(!n)throw new Error(`"${t.value}" is not a function this calculator has.`);if(!e.eat("("))throw new Error(`${t.value} needs brackets, as in ${t.value}(9).`);const o=u(e);if(!e.eat(")"))throw new Error("A bracket was opened and never closed.");return n(o)}function a(e){const t=s(e);return e.eat("^")?t**a(e):t}function i(e){let t=a(e);for(;;)if(e.eat("*"))t*=a(e);else if(e.eat("/"))t/=a(e);else if(e.eat("%"))t%=a(e);else return t}function u(e){let t=i(e);for(;;)if(e.eat("+"))t+=i(e);else if(e.eat("-"))t-=i(e);else return t}function d(e){const t=new w(f(e)),n=u(t);if(!t.done)throw new Error("There is something left over after the expression.");if(!Number.isFinite(n))throw new Error(n===1/0||n===-1/0?"That divides by zero.":"That is not a number.");return n}export{d as evaluate};

package/dist/builtin/clock/clock.js

@@ -1,61 +1 @@
-import { tool } from "../../tool/index.js";
-export function currentTime(opts = {}) {
-    const now = opts.now ?? (() => new Date());
-    return tool({
-        name: "current_time",
-        effect: "readonly",
-        description: "The current date and time. Call this before answering anything that " +
-            "depends on today's date — ages, deadlines, 'how long ago', 'this year'. " +
-            "Do not rely on your own sense of the date; it is the date you were " +
-            "trained, not today.",
-        args: [
-            {
-                name: "timezone",
-                type: "string",
-                required: false,
-                description: "IANA zone such as Europe/London or Asia/Kolkata. Defaults to the server's zone.",
-            },
-            {
-                name: "format",
-                type: "enum",
-                required: false,
-                options: ["iso", "human", "date", "time"],
-                description: "iso is unambiguous and the right default for anything machine-read.",
-            },
-        ],
-        run: ({ timezone, format = "iso" }) => {
-            const at = now();
-            const zone = timezone ?? opts.defaultTimeZone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
-            try {
-                new Intl.DateTimeFormat("en-GB", { timeZone: zone });
-            }
-            catch {
-                throw new Error(`"${zone}" is not a known IANA time zone.`);
-            }
-            const answerZone = format === "iso" ? "UTC" : zone;
-            const parts = (options) => new Intl.DateTimeFormat("en-GB", {
-                timeZone: answerZone,
-                ...options,
-            }).format(at);
-            const formatted = format === "human"
-                ? parts({ dateStyle: "full", timeStyle: "short" })
-                : format === "date"
-                    ? parts({ year: "numeric", month: "2-digit", day: "2-digit" })
-                    : format === "time"
-                        ? parts({
-                            hour: "2-digit",
-                            minute: "2-digit",
-                            second: "2-digit",
-                            hour12: false,
-                        })
-                        : at.toISOString();
-            return {
-                now: formatted,
-                iso: at.toISOString(),
-                timezone: answerZone,
-                unix: Math.floor(at.getTime() / 1000),
-                weekday: parts({ weekday: "long" }),
-            };
-        },
-    });
-}
+import{tool as m}from"../../tool/index.js";function h(i={}){const r=i.now??(()=>new Date);return m({name:"current_time",effect:"readonly",description:"The current date and time. Call this before answering anything that depends on today's date \u2014 ages, deadlines, 'how long ago', 'this year'. Do not rely on your own sense of the date; it is the date you were trained, not today.",args:[{name:"timezone",type:"string",required:!1,description:"IANA zone such as Europe/London or Asia/Kolkata. Defaults to the server's zone."},{name:"format",type:"enum",required:!1,options:["iso","human","date","time"],description:"iso is unambiguous and the right default for anything machine-read."}],run:({timezone:s,format:e="iso"})=>{const t=r(),o=s??i.defaultTimeZone??Intl.DateTimeFormat().resolvedOptions().timeZone;try{new Intl.DateTimeFormat("en-GB",{timeZone:o})}catch{throw new Error(`"${o}" is not a known IANA time zone.`)}const a=e==="iso"?"UTC":o,n=d=>new Intl.DateTimeFormat("en-GB",{timeZone:a,...d}).format(t);return{now:e==="human"?n({dateStyle:"full",timeStyle:"short"}):e==="date"?n({year:"numeric",month:"2-digit",day:"2-digit"}):e==="time"?n({hour:"2-digit",minute:"2-digit",second:"2-digit",hour12:!1}):t.toISOString(),iso:t.toISOString(),timezone:a,unix:Math.floor(t.getTime()/1e3),weekday:n({weekday:"long"})}}})}export{h as currentTime};

package/dist/builtin/clock/index.js

@@ -1 +1 @@
-export { currentTime } from "./clock.js";
+import{currentTime as m}from"./clock.js";export{m as currentTime};

package/dist/builtin/code-exec/code-exec.d.ts

@@ -0,0 +1,28 @@
+export interface SandboxRequest {
+    code: string;
+    language: string;
+    timeoutMs: number;
+}
+export interface SandboxResult {
+    ok: boolean;
+    stdout: string;
+    stderr?: string;
+    timedOut?: boolean;
+    costMicroUsd?: number;
+}
+export interface Sandbox {
+    execute(request: SandboxRequest): Promise<SandboxResult>;
+}
+export interface CodeExecOptions {
+    sandbox: Sandbox;
+    language?: string;
+    timeoutMs?: number;
+    maxChars?: number;
+}
+export declare function codeExec(opts: CodeExecOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "code";
+    readonly type: "text";
+    readonly required: true;
+    readonly maxLength: 10000;
+    readonly description: `A complete ${string} program that prints its result.`;
+}]>>;

package/dist/builtin/code-exec/code-exec.js

@@ -0,0 +1 @@
+import{tool as d}from"../../tool/index.js";const u="python",l=1e4,h=2e4,m=1e4;function i(e,t){return{text:e.slice(0,t),overflowed:e.length>t}}function x(e){if(!e.sandbox)throw new Error("codeExec needs a sandbox to execute in, and there is no default: this package ships none, because running model-written code in this process is arbitrary code execution with extra steps.");const t=e.language??u,o=e.timeoutMs??l,r=e.maxChars??h;return d({name:"code_exec",description:`Runs a short ${t} program in a sandbox and hands back what it printed. Use it for work an arithmetic expression cannot state \u2014 sorting, filtering, joining, parsing or summing data you already have. Print the answer; a value left unprinted comes back as nothing. There is no network and no filesystem, nothing survives between calls, and a run longer than ${o}ms is cut off.`,args:[{name:"code",type:"text",required:!0,maxLength:m,description:`A complete ${t} program that prints its result.`}],run:async({code:c})=>{const n=await e.sandbox.execute({code:c,language:t,timeoutMs:o}),s=i(n.stdout??"",r),a=i(n.stderr??"",r);return{ok:n.ok,stdout:s.text,stderr:a.text,truncated:s.overflowed||a.overflowed,timedOut:n.timedOut===!0,...n.costMicroUsd===void 0?{}:{costMicroUsd:n.costMicroUsd}}}})}export{x as codeExec};

package/dist/builtin/code-exec/index.d.ts

@@ -0,0 +1 @@
+export { type CodeExecOptions, codeExec, type Sandbox, type SandboxRequest, type SandboxResult, } from "./code-exec.js";

package/dist/builtin/code-exec/index.js

@@ -0,0 +1 @@
+import{codeExec as c}from"./code-exec.js";export{c as codeExec};

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 f,parseDate as d,shift as u}from"./shift.js";const c=["seconds","minutes","hours","days","weeks","months","years"];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. 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:[...c]},{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 a=d(s,"date");if(e==="difference"){if(!n)throw new Error("difference needs a second date in `to`.");return{unit:t,difference:f(a,d(n,"to"),t)}}if(r===void 0)throw new Error(`${e} needs an \`amount\`.`);const o=u(a,e==="subtract"?-r:r,t);return{iso:o.toISOString(),date:o.toISOString().slice(0,10)}}})}export{h as dateMath};

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 o,parseDate as f,shift as p}from"./shift.js";export{o as between,r as dateMath,f as parseDate,p as shift};

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 o={seconds:1e3,minutes:6e4,hours:36e5,days:864e5,weeks:6048e5};function i(e,n){const t=new Date(e);if(!Number.isFinite(t.getTime()))throw new Error(`${n} "${e}" is not a date. Use an ISO instant, as in 2026-03-31.`);return t}function a(e,n){const t=e.getUTCDate(),s=new Date(e.getTime());s.setUTCDate(1),s.setUTCMonth(s.getUTCMonth()+n);const r=new Date(Date.UTC(s.getUTCFullYear(),s.getUTCMonth()+1,0)).getUTCDate();return s.setUTCDate(Math.min(t,r)),s}function h(e,n,t){if(!Number.isInteger(n))throw new Error("amount must be a whole number.");if(t==="months")return a(e,n);if(t==="years")return a(e,n*12);const s=o[t];if(!s)throw new Error(`"${t}" is not a unit this tool knows.`);return new Date(e.getTime()+n*s)}function T(e,n,t){if(t==="months"||t==="years"){const r=(n.getUTCFullYear()-e.getUTCFullYear())*12+(n.getUTCMonth()-e.getUTCMonth())-(n.getUTCDate()<e.getUTCDate()?1:0);return t==="years"?Math.trunc(r/12):r}const s=o[t];if(!s)throw new Error(`"${t}" is not a unit this tool knows.`);return Math.trunc((n.getTime()-e.getTime())/s)}export{T as between,i as parseDate,h as shift};

package/dist/builtin/deep-recall/deep-recall.d.ts

@@ -1,7 +1,44 @@
-import type { LocusGraphClient } from "@locusgraph/client";
+/** One piece of evidence, with where it came from. */
+export interface RecalledFact {
+    text: string;
+    locus: string;
+    contexts: string[];
+    score: number;
+    source?: string;
+}
+/** What a deep recall answered, and what answering it cost. */
+export interface RecallResult {
+    facts: RecalledFact[];
+    contexts_walked: string[];
+    summary?: string;
+    coverage: "full" | "partial";
+    fallback: boolean;
+    usage: {
+        cost_usd: number;
+    };
+}
+/**
+ * Anything that can answer a deep recall — a `LocusGraphClient`, or a test
+ * double.
+ *
+ * Declared structurally rather than imported, for the reason `prompt` declares
+ * its own `Recordable` and `llms` reads provider replies as plain objects: a
+ * type-only import still puts `@locusgraph/client` in `dependencies`, so every
+ * install of this package downloaded a client that nothing here ever loads, and
+ * every consumer's typecheck needed it resolvable to read one `.d.ts`. A real
+ * client satisfies this, which `tests/structural.test.ts` proves with the
+ * package still on hand as a devDependency.
+ */
+export interface Recaller {
+    deepRecall(query: {
+        question: string;
+        graphId?: string;
+        contextIds?: string[];
+    }): Promise<RecallResult>;
+}
 export interface DeepRecallOptions {
     /** A `LocusGraphClient`, or anything carrying its `deepRecall`. */
-    client: Pick<LocusGraphClient, "deepRecall">;
+    client: Recaller;
     /** Graph the walk runs over. Unset, the client's own default is used. */
     graphId?: string;
     /** Longest evidence list handed back. Default 20. */

package/dist/builtin/deep-recall/deep-recall.js

@@ -1,45 +1 @@
-import { tool } from "../../tool/index.js";
-const DEFAULT_MAX_FACTS = 20;
-export function deepRecall(opts) {
-    const maxFacts = opts.maxFacts ?? DEFAULT_MAX_FACTS;
-    return tool({
-        name: "deep_recall",
-        description: "Searches your own knowledge base and returns an answer with the evidence it rests " +
-            "on. A walker follows linked contexts, so it answers questions spread across several " +
-            "notes — what do we know about X, what was decided and why. Ask one focused thing. " +
-            "Prefer it over a web search whenever the answer could already be in your records.",
-        effect: "readonly",
-        args: [
-            {
-                name: "question",
-                type: "string",
-                required: true,
-                maxLength: 1000,
-                description: "One focused question, not a conversation and not several at once.",
-            },
-            {
-                name: "context_ids",
-                type: "list",
-                required: false,
-                description: "Contexts to start the walk from, as type:name — take them from the contexts of " +
-                    "an earlier result. A hint, not a filter; the walk may go elsewhere.",
-            },
-        ],
-        run: async ({ question, context_ids }) => {
-            const result = await opts.client.deepRecall({
-                question,
-                ...(opts.graphId ? { graphId: opts.graphId } : {}),
-                ...(context_ids?.length ? { contextIds: context_ids } : {}),
-            });
-            return {
-                summary: result.summary,
-                facts: result.facts.slice(0, maxFacts),
-                truncated: result.facts.length > maxFacts,
-                contextsWalked: result.contexts_walked,
-                coverage: result.coverage,
-                fallback: result.fallback,
-                costMicroUsd: Math.round(result.usage.cost_usd * 1_000_000),
-            };
-        },
-    });
-}
+import{tool as s}from"../../tool/index.js";const o=20;function l(t){const a=t.maxFacts??o;return s({name:"deep_recall",description:"Searches your own knowledge base and returns an answer with the evidence it rests on. A walker follows linked contexts, so it answers questions spread across several notes \u2014 what do we know about X, what was decided and why. Ask one focused thing. Prefer it over a web search whenever the answer could already be in your records.",effect:"readonly",args:[{name:"question",type:"string",required:!0,maxLength:1e3,description:"One focused question, not a conversation and not several at once."},{name:"context_ids",type:"list",required:!1,description:"Contexts to start the walk from, as type:name \u2014 take them from the contexts of an earlier result. A hint, not a filter; the walk may go elsewhere."}],run:async({question:n,context_ids:r})=>{const e=await t.client.deepRecall({question:n,...t.graphId?{graphId:t.graphId}:{},...r?.length?{contextIds:r}:{}});return{summary:e.summary,facts:e.facts.slice(0,a),truncated:e.facts.length>a,contextsWalked:e.contexts_walked,coverage:e.coverage,fallback:e.fallback,costMicroUsd:Math.round(e.usage.cost_usd*1e6)}}})}export{l as deepRecall};

package/dist/builtin/deep-recall/index.d.ts

@@ -1 +1 @@
-export { type DeepRecallOptions, deepRecall } from "./deep-recall.js";
+export { type DeepRecallOptions, deepRecall, type RecalledFact, type Recaller, type RecallResult, } from "./deep-recall.js";

package/dist/builtin/deep-recall/index.js

@@ -1 +1 @@
-export { deepRecall } from "./deep-recall.js";
+import{deepRecall as o}from"./deep-recall.js";export{o as deepRecall};

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 i}from"../../tool/index.js";function u(e={}){return i({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:a,summary:t,urgency:r="normal"})=>{const n={reason:a,summary:t,urgency:r},o=e.onEscalate?await e.onEscalate(n):void 0;return{escalated:!0,delivered:!!e.onEscalate,request:n,handled:o}}})}export{u as escalate};

package/dist/builtin/escalate/index.js

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

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",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};