@spendgraph/tools 0.2.0

package/README.md

@@ -0,0 +1,283 @@
+# @spendgraph/tools
+
+Declare a tool once, offer the right few, and record what was called.
+
+```sh
+npm install @spendgraph/tools
+```
+
+Three things are exported. Everything else hangs off what they return.
+
+```ts
+import { tool, toolbus, currentTime } from "@spendgraph/tools";
+```
+
+## Declaring one
+
+A description the model reads and a function you wrote, in one object. Splitting
+them — a schema here, a handler there, matched by string — is how a rename
+becomes a runtime failure mid-loop.
+
+```ts
+const lookup = tool({
+  name: "lookup_contract",
+  description: "Finds a contract clause by its reference, such as MSA 2.4.",
+  args: [
+    { name: "ref", type: "string", required: true },
+    { name: "limit", type: "number", required: false },
+    { name: "mode", type: "enum", required: false, options: ["fast", "thorough"] },
+  ] as const,
+  run: ({ ref, limit, mode }) => search(ref, limit ?? 5, mode ?? "fast"),
+});
+```
+
+**Write `as const` and the handler types itself.** `ref` arrives a string,
+`limit` a number, `mode` narrowed to its two options, and the optional ones
+optional. Rename an argument and the handler stops compiling — rather than being
+handed `undefined` halfway through an agent loop.
+
+The description is the biggest lever on whether the model calls it correctly, and
+worth iterating on more than the code is.
+
+Every check `tool` makes is something a provider either rejects opaquely or
+accepts and behaves oddly about — a name a provider will not take, an enum with
+no options, a blank option the model can legally pick and you cannot act on.
+They fire at import, not on the first loop in production.
+
+## What a tool does
+
+```ts
+tool({
+  name: "issue_refund",
+  description: "Refund a charge to the original card.",
+  effect: "destructive",
+  args,
+  run,
+});
+```
+
+Without it `issue_refund` and `lookup_clause` are the same thing to a bus: two
+names with schemas. Nothing can tell what is safe to retry, safe to run twice,
+or worth asking a person about first.
+
+| | |
+| --- | --- |
+| `readonly` | no effect outside the process |
+| `idempotent` | has an effect, but twice is the same as once |
+| `destructive` | neither, so never retry it on its own |
+
+Three values, not a taxonomy — anything finer does not get filled in
+accurately.
+
+**There is no default, and unset is not `readonly`.** A default would quietly
+label every tool written before this existed as safe, which is the one mistake
+that matters here. Unset means nobody has said.
+
+```ts
+bus.effectOf("issue_refund")   // "destructive", or undefined if it never said
+bus.destructive()              // ["issue_refund"]
+bus.unannotated()              // ["send_email"]
+```
+
+`destructive()` returns only the tools that said so, so a gate built on it alone
+lets an unlabelled one through. `unannotated()` is how you find those — assert
+it is empty in a test and a new tool cannot join the bus unlabelled.
+
+It rides along on `declarations()` and survives `select()`, which is where a
+gate reads it. Every provider shape drops it: no API has a field for it, and an
+unknown key is rejected or ignored.
+
+Two builtins leave it unset on purpose. `http_request` is a GET or a POST
+depending on an argument, and one label cannot be true of both; `escalate` runs
+your `onEscalate`, and paging someone twice is not the same as paging them once.
+
+## The bus
+
+```ts
+const bus = toolbus([lookup, currentTime()], { limit: 6 });
+```
+
+Holding them in one place is what makes selection possible. Fifty tools at
+roughly 150 tokens of declaration each is 7.5k tokens on every call before the
+user has said anything, so past a point you stop sending all of them.
+
+```ts
+bus.select(query)          // the working set for one request
+bus.anthropic(decls?)      // declarations, per provider
+bus.openai(decls?)
+bus.markdown(decls?)       // for a model with no tools API
+await bus.invoke(name, args)
+bus.missing(["refund"])    // names something expects that this bus lacks
+bus.usage()
+```
+
+`limit` is an accuracy budget, not a token one: more tools in front of a model
+makes it worse at picking the right one regardless of context length. Measured
+shortlists cluster around five to eight. Pinned tools count against it.
+
+Selection is keyword and usage, deliberately — no embedding provider, no extra
+call, no latency. It is also the baseline that says what embeddings would buy.
+
+`missing` catches a silent failure: a prompt edited to expect a `refund` tool,
+deployed against a bus without one, does not error. The agent is never offered it
+and answers anyway.
+
+## One turn
+
+```ts
+const turn = bus.trace(query);
+
+const reply = await llm.call(messages, { tools: turn });
+await turn.invoke(call.name, call.args);
+
+turn.record();   // { offeredTools, steps }
+```
+
+A turn is selected once and remembers what it offered. Which tools were offered
+is recorded as well as which were called: without it a record cannot tell "chose
+not to" from "was never offered", which are opposite bugs.
+
+It plugs straight into `@spendgraph/prompt` — `call` and `invoke` take anything
+that hands out a turn, and neither package imports the other.
+
+```ts
+await prompt.call(values, ({ messages, turn }) => llm.call(messages, { tools: turn }), {
+  tools: bus,
+});
+```
+
+## Builtins
+
+Eight, each a factory, none registered for you — this package's own advice is
+that more tools in front of a model makes it worse at picking, so they are opt-in
+one at a time.
+
+```ts
+import { calculate, currentTime, escalate, finish, think, httpRequest } from "@spendgraph/tools";
+
+const bus = toolbus([
+  calculate(),
+  think(),
+  finish(),
+  currentTime({ defaultTimeZone: "Europe/London" }),
+  escalate({ onEscalate: (r) => pager.page(r) }),
+  httpRequest({ allow: [".example.com"], headers: { authorization: `Bearer ${key}` } }),
+]);
+```
+
+| | |
+| --- | --- |
+| `calculate()` | arithmetic, **parsed not evaluated** |
+| `think()` | a scratchpad that does nothing |
+| `finish()` | the model says it is done, and what the answer is |
+| `currentTime()` | the clock a model does not have |
+| `escalate()` | hand back to a person; `pinned` by default |
+| `httpRequest()` | a GET or POST to hosts you named |
+| `dateMath()` | add, subtract and difference, in whole units |
+| `jsonQuery()` | one value out of a JSON document, by path |
+| `writeDocument()` | a document agent that returns a rendered file |
+
+**`calculate`** parses the expression — numbers, `+ - * / % ^`, brackets, and
+`sqrt abs round floor ceil ln log` — and refuses everything else. `eval` on model
+output is arbitrary code execution with extra steps.
+
+**`think`** returns `"noted"` and changes nothing. That is the point: the thought
+lands in the steps instead of in the reply, and a model given room to plan before
+a multi-step sequence uses the tools better.
+
+**`finish`** gives a loop a real stop condition. Without it a run ends when the
+model goes quiet, which is indistinguishable from it losing the thread. Read the
+result with `isFinished(result)` and `answerOf(result)`.
+
+**`escalate`** is `pinned: true`, because a refusal route lost to a similarity
+score is exactly the failure `pinned` exists for — the one turn that needs it is
+the turn where nothing else fit. Without an `onEscalate` it records the request
+and reports `delivered: false`, rather than letting the model believe a person
+was reached.
+
+**`dateMath`** is what `current_time` leads to: the clock says when now is, this
+works out what follows. Calendar months clamp rather than overflow — a month
+after 31 January is 28 February, not 3 March, which is what `setMonth` gives and
+what every billing system disagrees with. `difference` counts boundaries crossed
+rather than dividing elapsed milliseconds, because a month is not 30 days and a
+year is not 365.
+
+**`jsonQuery`** reads one value out of a document by path — `invoices[0].total`,
+or `invoices[*].total` for every element. After a wildcard the rest of the path
+keeps applying to each element, so `invoices[*].lines[0].sku` is the first line
+of every invoice, not the lines of the first. A path that matches nothing comes
+back `found: false` rather than `null`, which a model would otherwise read as the
+answer.
+
+**`httpRequest`** takes a **required** allowlist and has no default. It is https
+only, refuses private, loopback, link-local and `.internal`/`.local` hosts even
+if you list them, and sets headers itself so a credential is never something the
+model can redirect. `"api.example.com"` matches that host; `".example.com"`
+matches it and any subdomain. If the guard feels heavy, that is the correct
+amount of heavy: this is the one builtin that can exfiltrate.
+
+## `current_time`
+
+```ts
+toolbus([currentTime({ defaultTimeZone: "Europe/London" })]);
+```
+
+A model has no clock, and asked for today's date it will confidently produce its
+training cutoff. A wrong IANA zone throws rather than falling back, because a
+confidently wrong time is the failure this exists to stop.
+
+## `write_document`
+
+```ts
+toolbus([
+  writeDocument({
+    apiKey: env.MOA_API_KEY,
+    design: {
+      name: "Northwind",
+      fonts: { heading: "Söhne" },
+      palette: { accent: "#E11D48" },
+      rules: ["Never set body text below 11pt."],
+    },
+  }),
+]);
+```
+
+Commissions a Moa agent to write and render a real file — `.pdf`, `.pptx`,
+`.docx`, `.md` — and hands back where to download it. Everything else in this
+package answers a question; this one produces the document somebody opens.
+
+Style is the deployment's business and content is the model's. `design` is laid
+over `DEFAULT_DESIGN`: named fields win, `rules` accumulate, and the merged
+guide is rendered into the task as a `<design>` block along with the craft that
+belongs to the format asked for — a deck gets "one idea per slide, the title is
+the claim", a PDF gets "nothing straddles a page break". The model may pass
+`design_notes` to bend the guide for one document; it cannot replace it.
+
+A rendered document is minutes, so the wait defaults to ten of them and
+long-polls rather than tight-polls. When even that runs out the result comes
+back `status: "running"` with the `taskId`, because the money is already spent
+and a lost id makes the model commission it twice. Stop the turn and the task is
+cancelled server-side.
+
+It is the one builtin marked `destructive`, and not because it breaks anything:
+a second call is a second bill and a second set of files, so it is never safe to
+retry on its own.
+
+## Examples
+
+Eight of them under [`examples/`](./examples), all runnable with no API key and
+no network — tools are local code; the model only decides which to call.
+
+```sh
+npm run build
+node examples/02-select/01-shortlist.mjs
+```
+
+## Subpaths
+
+| | |
+| --- | --- |
+| `@spendgraph/tools/wire` | `toAnthropic` · `toOpenAI` · `toJsonSchema` · `toMarkdown` |
+| `@spendgraph/tools/internals` | `selectTools` · `score` · `invokeTool` · `newTrace` · `toStep` · `warnOnOverlap` |
+
+A bus already wires all of `internals`; reach for it to build your own.

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

@@ -0,0 +1,13 @@
+/**
+ * Arithmetic, because a model does it from memory and is confidently wrong.
+ *
+ * The expression is parsed, never evaluated — `eval` on model output is
+ * arbitrary code execution with extra steps.
+ */
+export declare function calculate(): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "expression";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 500;
+    readonly description: "For example (1250 * 0.2) + 99, or sqrt(144).";
+}]>>;

package/dist/builtin/calculate/calculate.js

@@ -0,0 +1,27 @@
+import { tool } from "../../tool/index.js";
+import { evaluate } from "./parse.js";
+/**
+ * Arithmetic, because a model does it from memory and is confidently wrong.
+ *
+ * The expression is parsed, never evaluated — `eval` on model output is
+ * arbitrary code execution with extra steps.
+ */
+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),
+    });
+}

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

@@ -0,0 +1,2 @@
+export { calculate } from "./calculate.js";
+export { evaluate } from "./parse.js";

package/dist/builtin/calculate/index.js

@@ -0,0 +1,2 @@
+export { calculate } from "./calculate.js";
+export { evaluate } from "./parse.js";

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

@@ -0,0 +1,8 @@
+/**
+ * Arithmetic, parsed rather than evaluated.
+ *
+ * `eval` on model output is arbitrary code execution with extra steps. This
+ * reads numbers, the five operators, brackets and a short list of functions,
+ * and refuses everything else.
+ */
+export declare function evaluate(expression: string): number;

package/dist/builtin/calculate/parse.js

@@ -0,0 +1,144 @@
+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;
+    }
+}
+/**
+ * Arithmetic, parsed rather than evaluated.
+ *
+ * `eval` on model output is arbitrary code execution with extra steps. This
+ * reads numbers, the five operators, brackets and a short list of functions,
+ * and refuses everything else.
+ */
+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;
+}

package/dist/builtin/clock/clock.d.ts

@@ -0,0 +1,27 @@
+export interface ClockOptions {
+    /** Injectable clock, so a test does not depend on the day it runs. */
+    now?: () => Date;
+    /** Used when the caller names none. Defaults to the host's zone. */
+    defaultTimeZone?: string;
+}
+/**
+ * What time it is.
+ *
+ * The one thing every model is confidently wrong about: weights are frozen at
+ * training time, so "today" is answered fluently from a stale date.
+ *
+ * Built in because every agent needs it and the common mistake — a formatted
+ * string with no zone — is a different instant depending on where it ran.
+ */
+export declare function currentTime(opts?: ClockOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "timezone";
+    readonly type: "string";
+    readonly required: false;
+    readonly description: "IANA zone such as Europe/London or Asia/Kolkata. Defaults to the server's zone.";
+}, {
+    readonly name: "format";
+    readonly type: "enum";
+    readonly required: false;
+    readonly options: readonly ["iso", "human", "date", "time"];
+    readonly description: "iso is unambiguous and the right default for anything machine-read.";
+}]>>;

package/dist/builtin/clock/clock.js

@@ -0,0 +1,76 @@
+import { tool } from "../../tool/index.js";
+/**
+ * What time it is.
+ *
+ * The one thing every model is confidently wrong about: weights are frozen at
+ * training time, so "today" is answered fluently from a stale date.
+ *
+ * Built in because every agent needs it and the common mistake — a formatted
+ * string with no zone — is a different instant depending on where it ran.
+ */
+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;
+            // Thrown rather than silently falling back: a wrong zone gives a
+            // confidently wrong time, which is the failure this tool exists to stop.
+            try {
+                new Intl.DateTimeFormat("en-GB", { timeZone: zone });
+            }
+            catch {
+                throw new Error(`"${zone}" is not a known IANA time zone.`);
+            }
+            // `iso` is a UTC instant, so the whole answer is UTC. Formatting the
+            // weekday in the requested zone while reporting UTC put Saturday and
+            // Sunday in one object near midnight.
+            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();
+            // The zone travels with the answer, and every field uses the one named.
+            return {
+                now: formatted,
+                iso: at.toISOString(),
+                timezone: answerZone,
+                unix: Math.floor(at.getTime() / 1000),
+                weekday: parts({ weekday: "long" }),
+            };
+        },
+    });
+}

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

@@ -0,0 +1 @@
+export { type ClockOptions, currentTime } from "./clock.js";

package/dist/builtin/clock/index.js

@@ -0,0 +1 @@
+export { currentTime } from "./clock.js";

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

@@ -0,0 +1,32 @@
+/**
+ * Date arithmetic, because a model does it in its head and drops a leap year.
+ *
+ * `current_time` says when now is; this works out what follows from it —
+ * deadlines, ages, notice periods, how long ago something was.
+ */
+export declare function dateMath(): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "operation";
+    readonly type: "enum";
+    readonly required: true;
+    readonly options: readonly ["add", "subtract", "difference"];
+}, {
+    readonly name: "date";
+    readonly type: "string";
+    readonly required: true;
+    readonly description: "ISO, as in 2026-03-31.";
+}, {
+    readonly name: "unit";
+    readonly type: "enum";
+    readonly required: true;
+    readonly options: readonly ["seconds", "minutes", "hours", "days", "weeks", "months", "years"];
+}, {
+    readonly name: "amount";
+    readonly type: "number";
+    readonly required: false;
+    readonly description: "For add and subtract.";
+}, {
+    readonly name: "to";
+    readonly type: "string";
+    readonly required: false;
+    readonly description: "The other date, for difference.";
+}]>>;

package/dist/builtin/date/date.js

@@ -0,0 +1,47 @@
+import { tool } from "../../tool/index.js";
+import { between, parseDate, shift } from "./shift.js";
+const UNITS = ["seconds", "minutes", "hours", "days", "weeks", "months", "years"];
+/**
+ * Date arithmetic, because a model does it in its head and drops a leap year.
+ *
+ * `current_time` says when now is; this works out what follows from it —
+ * deadlines, ages, notice periods, how long ago something was.
+ */
+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) };
+        },
+    });
+}

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

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