@spendgraph/tools 0.2.0 → 0.3.0

package/README.md

@@ -172,9 +172,9 @@ const bus = toolbus([
 | `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 |
+| `httpRequest()` | a GET or POST to hosts you named |
 | `writeDocument()` | a document agent that returns a rendered file |
 
 **`calculate`** parses the expression — numbers, `+ - * / % ^`, brackets, and
@@ -189,6 +189,11 @@ a multi-step sequence uses the tools better.
 model goes quiet, which is indistinguishable from it losing the thread. Read the
 result with `isFinished(result)` and `answerOf(result)`.
 
+**`current_time`** is the clock a model does not have. Asked for today's date it
+will otherwise produce its training cutoff, confidently. A wrong IANA zone throws
+rather than falling back, because a confidently wrong time is the failure this
+exists to stop.
+
 **`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
@@ -216,16 +221,6 @@ 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
@@ -281,3 +276,7 @@ node examples/02-select/01-shortlist.mjs
 | `@spendgraph/tools/internals` | `selectTools` · `score` · `invokeTool` · `newTrace` · `toStep` · `warnOnOverlap` |
 
 A bus already wires all of `internals`; reach for it to build your own.
+
+## License
+
+MIT

package/dist/builtin/calculate/calculate.js

@@ -1,11 +1,5 @@
 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",

package/dist/builtin/calculate/parse.js

@@ -125,13 +125,6 @@ function additive(r) {
             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);

package/dist/builtin/clock/clock.js

@@ -1,13 +1,4 @@
 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({
@@ -35,17 +26,12 @@ export function currentTime(opts = {}) {
         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,
@@ -63,7 +49,6 @@ export function currentTime(opts = {}) {
                             hour12: false,
                         })
                         : at.toISOString();
-            // The zone travels with the answer, and every field uses the one named.
             return {
                 now: formatted,
                 iso: at.toISOString(),

package/dist/builtin/date/date.js

@@ -1,12 +1,6 @@
 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",

package/dist/builtin/date/shift.js

@@ -5,7 +5,6 @@ const MS = {
     days: 86_400_000,
     weeks: 604_800_000,
 };
-/** Parses an ISO instant, or says which argument was not one. */
 export function parseDate(value, label) {
     const at = new Date(value);
     if (!Number.isFinite(at.getTime())) {
@@ -13,13 +12,6 @@ export function parseDate(value, label) {
     }
     return at;
 }
-/**
- * Adds calendar months, clamping rather than overflowing.
- *
- * `setUTCMonth` turns 31 January plus one month into 3 March, which is nobody's
- * idea of a month later. The last day of a short month is the answer people
- * mean, and the answer every billing system gives.
- */
 function addMonths(from, months) {
     const day = from.getUTCDate();
     const shifted = new Date(from.getTime());
@@ -29,7 +21,6 @@ function addMonths(from, months) {
     shifted.setUTCDate(Math.min(day, lastOfMonth));
     return shifted;
 }
-/** Moves an instant by a whole number of units. Negative goes backwards. */
 export function shift(from, amount, unit) {
     if (!Number.isInteger(amount))
         throw new Error("amount must be a whole number.");
@@ -42,12 +33,6 @@ export function shift(from, amount, unit) {
         throw new Error(`"${unit}" is not a unit this tool knows.`);
     return new Date(from.getTime() + amount * ms);
 }
-/**
- * How far apart two instants are, in whole units.
- *
- * Calendar units count boundaries crossed rather than dividing elapsed
- * milliseconds, because a month is not 30 days and a year is not 365.
- */
 export function between(from, to, unit) {
     if (unit === "months" || unit === "years") {
         const months = (to.getUTCFullYear() - from.getUTCFullYear()) * 12 +

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

@@ -1,11 +1,5 @@
 import { tool } from "../../tool/index.js";
 const DEFAULT_MAX_FACTS = 20;
-/**
- * Your own knowledge base, answered with cited evidence.
- *
- * Cost comes back as micro-USD because deep recall runs model calls of its own,
- * and that spend is invisible to whatever loop called this.
- */
 export function deepRecall(opts) {
     const maxFacts = opts.maxFacts ?? DEFAULT_MAX_FACTS;
     return tool({

package/dist/builtin/escalate/escalate.js

@@ -1,13 +1,4 @@
 import { tool } from "../../tool/index.js";
-/**
- * Hand back to a person rather than guess.
- *
- * An agent with no way to stop answers anyway, and a confident wrong answer to
- * something it could not do is worse than a handover.
- *
- * Its `effect` is left unset on purpose: `onEscalate` is yours, and paging
- * someone twice is not the same as paging them once.
- */
 export function escalate(opts = {}) {
     return tool({
         name: "escalate",

package/dist/builtin/finish/finish.js

@@ -1,10 +1,4 @@
 import { tool } from "../../tool/index.js";
-/**
- * True when this result is the model saying it is done.
- *
- * A loop that ends because the model stopped asking for tools cannot tell
- * finished from confused. This makes the difference explicit.
- */
 export function isFinished(result) {
     if (result.name !== "finish" || result.status !== "completed")
         return false;
@@ -15,18 +9,11 @@ export function isFinished(result) {
         return false;
     }
 }
-/** Reads the answer out of a finished result, or null if it is not one. */
 export function answerOf(result) {
     if (!isFinished(result))
         return null;
     return JSON.parse(result.output).answer;
 }
-/**
- * The model says it is done, and says what the answer is.
- *
- * Without it a loop ends by the model going quiet, which is indistinguishable
- * from it losing the thread.
- */
 export function finish() {
     return tool({
         name: "finish",

package/dist/builtin/http/allow.js

@@ -11,19 +11,11 @@ function isPrivateHost(host) {
         return true;
     return PRIVATE_V4.test(name);
 }
-/** Matches a host exactly, or any subdomain when the rule starts with a dot. */
 function matches(host, rule) {
     const h = host.toLowerCase();
     const r = rule.toLowerCase();
     return r.startsWith(".") ? h === r.slice(1) || h.endsWith(r) : h === r;
 }
-/**
- * The URL a request may go to, or the reason it may not.
- *
- * An allowlist rather than a blocklist, and https only. A tool that fetches
- * whatever a model names is how an agent reads a cloud metadata endpoint and
- * hands back the credentials it finds.
- */
 export function checkUrl(raw, allow) {
     let url;
     try {

package/dist/builtin/http/http.js

@@ -2,16 +2,6 @@ import { tool } from "../../tool/index.js";
 import { checkUrl } from "./allow.js";
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_MAX_CHARS = 100_000;
-/**
- * An HTTP GET or POST, to hosts you named.
- *
- * The allowlist is required because the alternative is a tool that fetches
- * whatever a model is talked into naming. Headers are set here, not by the
- * model, so a credential is never something it can redirect.
- *
- * 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.
- */
 export function httpRequest(opts) {
     if (!opts.allow?.length) {
         throw new Error("httpRequest needs an allow list of hosts; there is no safe default.");

package/dist/builtin/json/json.js

@@ -1,13 +1,6 @@
 import { tool } from "../../tool/index.js";
 import { readPath } from "./path.js";
 const DEFAULT_MAX_CHARS = 20_000;
-/**
- * Pulls one value out of a JSON document.
- *
- * The alternative is putting the whole reply in the context and asking the model
- * to read it, which costs tokens on every turn and gets the field wrong when the
- * document is long.
- */
 export function jsonQuery(opts = {}) {
     const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
     return tool({

package/dist/builtin/json/path.js

@@ -36,13 +36,6 @@ function step(value, segment) {
     }
     return value;
 }
-/**
- * Reads a value out of parsed JSON by path.
- *
- * `a.b`, `a[0].b`, and `a[*].b` for every element — enough to pull a field out
- * of an API reply, and small enough that the syntax is guessable from one
- * example, which matters when the thing writing the path is a model.
- */
 export function readPath(document, path) {
     let cursor = document;
     let spread = false;

package/dist/builtin/think/think.js

@@ -1,11 +1,4 @@
 import { tool } from "../../tool/index.js";
-/**
- * Somewhere to reason without it becoming the answer.
- *
- * It does nothing, which is the point: the thought lands in the steps rather
- * than in the reply, and a model given room to plan before a multi-step tool
- * sequence uses the tools better.
- */
 export function think() {
     return tool({
         name: "think",

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

@@ -5,14 +5,6 @@ function sources(raw) {
     }
     return (raw.citations ?? []).map((url) => ({ url }));
 }
-/**
- * The provider's reply as the tool hands it back.
- *
- * Sources come from `search_results` where the account returns them and from
- * `citations` otherwise, so one tool works across both reply shapes. Citation
- * and reasoning tokens are their own line items on a grounded model, and
- * `computeCostMicros` takes both — dropping them prices a paid call at zero.
- */
 export function readReply(body, fallbackModel, maxChars, maxResults) {
     const raw = body;
     const answer = raw.choices?.[0]?.message?.content ?? "";

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

@@ -22,14 +22,6 @@ function describe(maxDepth, domains) {
             : " deep is not enabled here.") +
         (domains?.length ? ` Results come only from ${domains.join(", ")}.` : ""));
 }
-/**
- * The live web, through Perplexity's Sonar models.
- *
- * The tier is the model's to choose and yours to cap: `sonar-deep-research` is
- * minutes and orders of magnitude, and a model reaching for it unprompted is
- * the failure `maxDepth` exists to prevent. Tokens come back rather than a
- * price, because what a search costs is the pricing table's business.
- */
 export function webSearch(opts) {
     if (!opts.apiKey?.trim()) {
         throw new Error("webSearch needs a Perplexity apiKey; it will not read one from the process.");

package/dist/builtin/write-document/commission.js

@@ -46,13 +46,6 @@ function taskText(input) {
         task += deliverablesBlock(input.artifacts);
     return task;
 }
-/**
- * HTTP {@link CommissionClient} over Moa's task API (`POST /tasks` → `GET /tasks/:id`).
- *
- * The request body carries the ask as prose — Moa's artifact pipeline is
- * prompt-driven and `POST /tasks` strips unknown fields, so context, design and
- * deliverables are blocks on the task rather than parameters beside it.
- */
 export function createCommissionClient(config = {}) {
     const request = createRequest(config);
     return {
@@ -92,12 +85,10 @@ export function createCommissionClient(config = {}) {
         },
     };
 }
-/** The sane ceiling for a chat-bound call. A rendered document wants minutes, not this. */
 export const INTERACTIVE_TIMEOUT_MS = 30_000;
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const SETTLE_ATTEMPTS = 3;
 const LONGPOLL_WINDOW_MS = 25_000;
-/** Thrown by {@link pollUntilDone} when the caller's abort signal fires. */
 export class CommissionAbortedError extends Error {
     commissionId;
     constructor(commissionId) {
@@ -106,7 +97,6 @@ export class CommissionAbortedError extends Error {
         this.commissionId = commissionId;
     }
 }
-/** Thrown when the wait ran out. The task itself is still running server-side. */
 export class CommissionTimeoutError extends Error {
     commissionId;
     timeoutMs;
@@ -126,7 +116,6 @@ const sleep = (ms, signal) => new Promise((resolve) => {
         resolve();
     }, ms);
 });
-/** Wait for a commission to settle, long-polling rather than tight-polling. */
 export async function pollUntilDone(client, id, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? INTERACTIVE_TIMEOUT_MS;
     const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;

package/dist/builtin/write-document/design.js

@@ -1,9 +1,3 @@
-/**
- * What a document looks like when nobody has said.
- *
- * Chosen to be defensible rather than distinctive: one typeface, one accent,
- * real whitespace, and figures that carry a single message.
- */
 export const DEFAULT_DESIGN = {
     name: "Spendgraph house style",
     fonts: { heading: "Inter", body: "Inter", mono: "JetBrains Mono" },
@@ -46,12 +40,6 @@ function mergeGroup(base, over) {
         return base;
     return { ...base, ...over };
 }
-/**
- * A caller's guide over the defaults: named fields win, `rules` accumulate.
- *
- * Rules append because they are constraints — a brand adding "never use red"
- * means it as well as the defaults, not instead of them.
- */
 export function mergeDesign(base, over) {
     if (!over)
         return base;
@@ -64,7 +52,6 @@ export function mergeDesign(base, over) {
     };
 }
 const line = (label, value) => (value ? [`${label}: ${value}`] : []);
-/** The guide as the block Moa reads, since its artifact pipeline is prompt-driven. */
 export function renderDesign(guide, format, notes) {
     const { fonts, palette } = guide;
     const parts = [

package/dist/builtin/write-document/http.js

@@ -1,8 +1,6 @@
-/** Where Moa lives, unless a config says otherwise. */
 export const MOA_BASE_URL = "https://api.fnmoa.com";
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 const ERROR_DETAIL_CHARS = 500;
-/** A non-2xx from Moa, carrying the status so a caller can tell 4xx from 5xx. */
 export class MoaApiError extends Error {
     status;
     detail;
@@ -37,7 +35,6 @@ function deadlineSignal(timeoutMs, caller) {
         },
     };
 }
-/** One `request<T>(path, opts)` against Moa, with auth, timeout and error shape settled. */
 export function createRequest(config = {}) {
     const doFetch = config.fetch ?? globalThis.fetch;
     const base = (config.baseUrl ?? MOA_BASE_URL).replace(/\/+$/, "");

package/dist/builtin/write-document/write-document.js

@@ -48,14 +48,6 @@ function stillRendering(id, style, err) {
             "say so rather than commissioning it again.",
     };
 }
-/**
- * A document agent, briefed in your house style.
- *
- * Style is the deployment's business and content is the model's: the guide
- * comes from `options.design`, and `design_notes` may bend it for one document
- * rather than replace it. `effect` is `destructive` because a second call is a
- * second bill and a second set of files — never something to retry blindly.
- */
 export function writeDocument(opts) {
     if (!opts.client && !opts.apiKey?.trim()) {
         throw new Error("writeDocument needs a Moa apiKey; it will not read one from the process.");

package/dist/bus/bus.js

@@ -4,16 +4,6 @@ import { warnOnOverlap } from "./overlap.js";
 import { selectTools } from "./select.js";
 import { toStep } from "./step.js";
 import { newTrace } from "./trace.js";
-/**
- * The tools an agent can reach, and how it reaches them.
- *
- * 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.
- *
- * 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.
- */
 export function toolbus(tools, opts = {}) {
     const now = opts.now ?? (() => Date.now());
     const ceiling = Math.max(1, opts.limit ?? 6);
@@ -23,7 +13,6 @@ export function toolbus(tools, opts = {}) {
             throw new Error(`Two tools are called "${t.name}".`);
         byName.set(t.name, t);
     }
-    /** How often each has been called, so the useful ones stay offered. */
     const calls = new Map();
     if (opts.warnOnOverlap ?? true)
         warnOnOverlap([...byName.values()]);
@@ -35,68 +24,25 @@ export function toolbus(tools, opts = {}) {
     });
     const all = () => [...byName.values()].map(declare);
     const bus = {
-        /** Every tool, in declaration order. */
         all: () => [...byName.values()],
-        /**
-         * Names something expects that this bus does not have.
-         *
-         * The failure it catches is silent: 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.
-         */
         missing: (names) => names.filter((n) => !byName.has(n)),
         get: (name) => byName.get(name),
-        /**
-         * What one tool declares calling it does. `undefined` when it never said.
-         *
-         * A gate reading this must decide what unknown means for it. It is not
-         * `readonly` — nothing has claimed that.
-         */
         effectOf: (name) => byName.get(name)?.effect,
-        /**
-         * Names of the tools declared `destructive`.
-         *
-         * Only the ones that said so. Pair it with `unannotated` before treating
-         * the rest as safe, or a tool nobody got round to labelling passes a gate
-         * built on this.
-         */
         destructive: () => [...byName.values()].filter((t) => t.effect === "destructive").map((t) => t.name),
-        /** Names of the tools with no effect declared, so a gate can refuse to guess. */
         unannotated: () => [...byName.values()].filter((t) => t.effect === undefined).map((t) => t.name),
-        /** Declarations for the model. Neutral shape; adapt per provider. */
         declarations: (names) => names
             ? names
                 .map((n) => byName.get(n))
                 .filter(Boolean)
                 .map((t) => declare(t))
             : all(),
-        /**
-         * Everything, in the shape the Anthropic Messages API takes.
-         *
-         * Selection is not applied for you — pass a shortlist to narrow it. The
-         * `tools` array sits ahead of the messages in the cached prefix, so a list
-         * that changes every turn invalidates the system prompt with it, and hiding
-         * the `select` call in here would hide that.
-         */
         anthropic: (decls) => toAnthropic(decls ?? all()),
-        /** Everything, in the shape the OpenAI chat completions API takes. */
         openai: (decls) => toOpenAI(decls ?? all()),
-        /**
-         * Everything as markdown, to append to a rendered system prompt.
-         *
-         * For a model with no tools API. Where there is one, prefer it: this is
-         * cheaper in tokens and worse in every other way.
-         */
         markdown: (decls, heading) => toMarkdown(decls ?? all(), heading),
-        /** The working set for one request. */
         select: (query = "", limit) => selectTools([...byName.values()], calls, declare, query, Math.max(1, limit ?? ceiling)),
-        /** Runs one, validating its arguments first. Never throws. */
         invoke: (name, args) => invokeTool(byName, calls, now, name, args),
-        /** How many times each has been called on this bus. */
         usage: () => Object.fromEntries(calls),
-        /** A result as a rollout step, for `report({ steps })`. */
         step: (result, index) => toStep(result, index),
-        /** One turn's tool use, selected once and recorded for the rollout. */
         trace: (query = "", limit) => newTrace(bus.select(query, limit), (name, args) => bus.invoke(name, args)),
     };
     return bus;

package/dist/bus/invoke.js

@@ -1,11 +1,4 @@
 import { FieldValidationError, validateFields } from "@spendgraph/sdk";
-/**
- * Runs one tool, validating its arguments first.
- *
- * Never throws. A tool that fails is an outcome the agent can react to and a
- * step worth recording, not an exception that ends the run — the same argument
- * `status` and `error` exist on a rollout for.
- */
 export async function invokeTool(byName, calls, now, name, args) {
     const started = now();
     const found = byName.get(name);

package/dist/bus/overlap.js

@@ -1,22 +1,10 @@
-/** Words long enough to carry meaning, for comparing two descriptions. */
 function words(tool) {
     return new Set(tool.description
         .toLowerCase()
         .split(/[^a-z0-9]+/)
         .filter((w) => w.length > 3));
 }
-/**
- * Warns once about tools that describe themselves the same way.
- *
- * Two near-identical descriptions are worse than one tool: the model cannot tell
- * them apart and picks wrong more often, with nothing failing. Said at
- * construction because it is invisible at runtime.
- *
- * One line however many pairs. A line each buries whatever else the process said
- * at startup and teaches people to switch the check off.
- */
 export function warnOnOverlap(tools) {
-    // Built once per tool, not once per pair — sixty tools is 1,770 pairs.
     const sets = tools.map(words);
     const named = [];
     let pairs = 0;

package/dist/bus/score.js

@@ -1,10 +1,3 @@
-/**
- * Overlap between the query and a tool's own words.
- *
- * The name counts for more than the description: "refund" in a question is a
- * stronger signal about the `refund` tool than the same word buried in a
- * paragraph about it.
- */
 export function score(tool, terms) {
     const name = tool.name.toLowerCase().replace(/_/g, " ");
     const body = `${tool.description} ${tool.args.map((a) => `${a.name} ${a.description ?? ""}`).join(" ")}`.toLowerCase();

package/dist/bus/select.js

@@ -1,20 +1,4 @@
 import { score } from "./score.js";
-/**
- * The working set for one request: pinned, then what the query matches, then
- * what actually gets used.
- *
- * Relevance before usage, which is the opposite of what this did first. At a
- * shortlist of twelve the order was harmless; at six, three previously-used
- * tools take half the slots and push out the tool the query needs.
- *
- * Usage still earns its place as the tiebreaker among equal matches, and as the
- * fallback when nothing matches — the case where an agent would otherwise be
- * handed nothing.
- *
- * How many come back depends on how clearly the query matched. A single strong
- * match needs no company; a flat spread means the ranking does not know, and a
- * wider net is worth the distraction.
- */
 export function selectTools(tools, calls, declare, query, ceiling) {
     const terms = query
         .toLowerCase()
@@ -25,8 +9,6 @@ export function selectTools(tools, calls, declare, query, ceiling) {
         if (!chosen.includes(t) && chosen.length < ceiling)
             chosen.push(t);
     };
-    // Counted against the ceiling like everything else: what is in front of the
-    // model is what costs accuracy, whoever put it there.
     for (const t of tools)
         if (t.pinned)
             take(t);
@@ -35,10 +17,6 @@ export function selectTools(tools, calls, declare, query, ceiling) {
         .map((t) => ({ t, n: score(t, terms) }))
         .filter((x) => x.n > 0)
         .sort((a, b) => b.n - a.n || (calls.get(b.t.name) ?? 0) - (calls.get(a.t.name) ?? 0));
-    // The depth applies to the slots selection is free to fill, not the whole
-    // list. Measured against the whole list it was a bug: four pinned tools
-    // already exceed a shortened target of three, so the loop below broke on its
-    // first iteration and dropped an exact name match with slots still free.
     const room = ceiling - chosen.length;
     const decisive = ranked.length > 1 && ranked[0].n >= ranked[1].n * 2;
     const budget = chosen.length + (decisive ? Math.min(3, room) : room);
@@ -47,8 +25,6 @@ export function selectTools(tools, calls, declare, query, ceiling) {
             break;
         take(t);
     }
-    // Up to the budget, not the ceiling — padding a decisive match back out to
-    // the full limit would undo the shortening entirely.
     const byUse = [...rest].sort((a, b) => (calls.get(b.name) ?? 0) - (calls.get(a.name) ?? 0));
     for (const t of byUse) {
         if (chosen.length >= budget)
@@ -57,9 +33,6 @@ export function selectTools(tools, calls, declare, query, ceiling) {
             break;
         take(t);
     }
-    // Only when the query singled out nothing. An agent handed no tools cannot
-    // act; an agent handed four unrelated ones alongside the obvious answer just
-    // has more to get wrong.
     if (ranked.length === 0) {
         for (const t of rest) {
             if (chosen.length >= ceiling)

package/dist/bus/step.js

@@ -1,4 +1,3 @@
-/** A result as a rollout step, for `report({ steps })`. */
 export function toStep(result, index) {
     return {
         index,

package/dist/bus/trace.js

@@ -1,17 +1,5 @@
 import { toAnthropic, toMarkdown, toOpenAI, } from "../wire/index.js";
 import { toStep } from "./step.js";
-/**
- * One turn's worth of tool use, holding the bookkeeping a rollout needs.
- *
- * Two things must survive from the moment a shortlist is chosen to the moment
- * the run is reported: which tools were offered, and what each call did in
- * order. Losing the first is worse than it sounds — a rollout that says the
- * agent never called `refund` cannot distinguish "chose not to" from "was never
- * offered it", which are opposite bugs.
- *
- * Selection happens once, here, and the same list is what gets reported. A trace
- * cannot disagree with itself about what the model saw.
- */
 export function newTrace(offered, invoke) {
     const steps = [];
     return {

package/dist/internals.js

@@ -1,9 +1,3 @@
-/**
- * The pieces `toolbus` is built from.
- *
- * Not in the main entry: a bus already wires all of it, and a caller reaching
- * here is building their own. Kept exported so that stays possible.
- */
 export { evaluate } from "./builtin/calculate/index.js";
 export { between, parseDate, shift } from "./builtin/date/index.js";
 export { checkUrl } from "./builtin/http/index.js";

package/dist/tool/bind.js

@@ -1,5 +1,4 @@
 import { tool } from "./tool.js";
-/** The stored declaration disagrees with the one this code was written against. */
 export class ToolDriftError extends Error {
     toolName;
     differences;
@@ -10,7 +9,6 @@ export class ToolDriftError extends Error {
         this.name = "ToolDriftError";
     }
 }
-/** Nothing is stored under that name, so there is no wording to bind to. */
 export class ToolNotStoredError extends Error {
     toolName;
     constructor(toolName) {
@@ -19,14 +17,6 @@ export class ToolNotStoredError extends Error {
         this.name = "ToolNotStoredError";
     }
 }
-/**
- * Every way the stored arguments differ from the declared ones.
- *
- * Compared by name, type and requiredness — the three a handler is written
- * against. A description or a bound that differs is the dashboard being edited,
- * which is the point; a renamed argument is a handler about to be passed
- * `undefined` halfway through an agent loop.
- */
 function drift(declared, stored) {
     const out = [];
     const byName = new Map(stored.map((a) => [a.name, a]));
@@ -49,27 +39,12 @@ function drift(declared, stored) {
     }
     return out;
 }
-/**
- * A stored declaration bound to the function that runs it.
- *
- * The dashboard owns the description, the effect and the pin — the parts you
- * iterate on and want live without a release. This code owns the arguments and
- * the handler, and the two are checked against each other on the way through:
- * a rename in the dashboard fails here, at bind time, rather than as an
- * `undefined` mid-loop.
- *
- * Declare `args` with `as const` as you would for `tool()`, or inference falls
- * back to `Record<string, unknown>` and the check above is the only thing left
- * catching a rename.
- */
 export async function bindTool(sg, spec, query = {}) {
     let stored;
     try {
         ({ tool: stored } = await sg.tools.get(spec.name, query));
     }
     catch (err) {
-        // A 404 is the ordinary case of "you have not written this one yet", and
-        // saying so beats a status code from three layers down.
         if (err && typeof err === "object" && "status" in err && err.status === 404) {
             throw new ToolNotStoredError(spec.name);
         }

package/dist/tool/tool.js

@@ -1,4 +1,3 @@
-/** Names a provider will accept: letters, digits and underscores. */
 const VALID_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const EFFECTS = ["readonly", "idempotent", "destructive"];
 function checkEnum(toolName, arg) {
@@ -30,16 +29,6 @@ function checkArgs(toolName, args) {
             checkEnum(toolName, arg);
     }
 }
-/**
- * Declares a tool, checking what is a silent failure otherwise.
- *
- * Every check here is something a provider either rejects opaquely or accepts
- * and behaves oddly about. Caught at import, not on the first loop in prod.
- *
- * Declare `args` with `as const` and `run` is typed from them — rename an
- * argument and the handler stops compiling, rather than being handed
- * `undefined` halfway through an agent loop.
- */
 export function tool(spec) {
     if (!VALID_NAME.test(spec.name)) {
         throw new Error(`Tool name "${spec.name}" must be letters, digits and underscores, starting with a letter.`);

package/dist/wire/json-schema.js

@@ -7,16 +7,6 @@ export const JSON_TYPE = {
     list: "array",
     json: "object",
 };
-/**
- * A field's default as a value of its own type.
- *
- * `FieldSpec.default` is already-rendered text, so `"5"` on a number field has
- * to come back as `5` — a schema saying `number` and defaulting to `"5"` is
- * something providers accept and models then copy.
- *
- * `list` and `json` defaults are joined and printed forms that cannot be parsed
- * back, so they are dropped rather than guessed at.
- */
 function coerceDefault(field) {
     const raw = field.default;
     if (raw === undefined)
@@ -43,12 +33,6 @@ function coerceDefault(field) {
             return raw;
     }
 }
-/**
- * `FieldSpec[]` as a JSON Schema object.
- *
- * `separator`, `trueText` and `falseText` are dropped: they interpolate a value
- * into a string, which a tool call does not do. So is `datasetKey`.
- */
 export function toJsonSchema(args) {
     const properties = {};
     for (const field of args) {

package/dist/wire/markdown.js

@@ -1,10 +1,4 @@
 import { JSON_TYPE } from "./json-schema.js";
-/**
- * Neutralises headings inside text about to become markdown.
- *
- * A `###` at the start of a line would close the tool's own section and open one
- * the prompt author never wrote.
- */
 function escapeHeadings(text) {
     return text.replace(/^(\s*)(#{1,6})(\s|$)/gm, "$1\\$2$3");
 }
@@ -24,13 +18,6 @@ function argLine(field) {
     const head = `- \`${field.name}\` (${type}${field.required ? ", required" : ""})`;
     return notes.length ? `${head} ${notes.join(". ")}.` : `${head}`;
 }
-/**
- * Declarations as markdown, for a model with no tools API.
- *
- * About a quarter cheaper than the JSON, since JSON Schema is mostly
- * scaffolding — but you give up structured tool calls and parse intent out of
- * prose instead. Only worth it where there is no native `tools` array.
- */
 export function toMarkdown(decls, heading = "## Tools") {
     if (decls.length === 0)
         return "";

package/dist/wire/providers.js

@@ -1,5 +1,4 @@
 import { toJsonSchema } from "./json-schema.js";
-/** Declarations in the shape the Anthropic Messages API takes. */
 export function toAnthropic(decls) {
     return decls.map((d) => ({
         name: d.name,
@@ -7,7 +6,6 @@ export function toAnthropic(decls) {
         input_schema: toJsonSchema(d.args),
     }));
 }
-/** Declarations in the shape the OpenAI chat completions API takes. */
 export function toOpenAI(decls) {
     return decls.map((d) => ({
         type: "function",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/tools",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Declare a tool once, offer the right few, and record what was called.",
   "license": "MIT",
   "repository": {
@@ -43,16 +43,16 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
     "test": "vitest run",
     "examples": "npm run build && node examples/02-select/01-shortlist.mjs"
   },
   "dependencies": {
     "@locusgraph/client": "^0.8.1",
-    "@spendgraph/sdk": "^0.2.0"
+    "@spendgraph/sdk": "^0.3.0"
   },
   "devDependencies": {
-    "@spendgraph/prompt": "^0.2.0",
+    "@spendgraph/prompt": "^0.3.0",
     "typescript": "^5"
   },
   "engines": {