@spendgraph/tools 0.5.0 → 0.6.0

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

@@ -1,86 +1,5 @@
-export const DEFAULT_DESIGN = {
-    name: "Spendgraph house style",
-    fonts: { heading: "Inter", body: "Inter", mono: "JetBrains Mono" },
-    palette: {
-        primary: "#0F172A",
-        accent: "#2563EB",
-        text: "#111827",
-        muted: "#64748B",
-        surface: "#FFFFFF",
-    },
-    layout: "A4 portrait, 20mm margins, a single text column at 60-75 characters, a 4pt spacing scale, " +
-        "and one heading scale used consistently (28/20/16/12). Whitespace is the design.",
-    charts: "One message per figure, stated in its caption. Label series directly where there are three " +
-        "or fewer. No 3D, no gradients, no gridline heavier than the data, no pie chart past three " +
-        "slices, and axes that start at zero unless the caption says why not.",
-    tone: "Plain and specific. Lead with the finding, then the evidence. No filler adjectives, no " +
-        "throat-clearing, no sentence that survives being deleted.",
-    rules: [
-        "A cover carrying the title, date and author, and no other ornament.",
-        "Every number traceable to something in the source material; invent nothing.",
-        "Tables for anything being compared; prose for anything being argued.",
-        "No stock imagery, no clip art, no placeholder text in the finished file.",
-        "Page numbers on every page after the cover.",
-    ],
-};
-const FORMAT_CRAFT = {
-    pdf: "Cover, then contents if it runs past four pages, then the body. Figures captioned and " +
-        "referenced from the text. Nothing straddles a page break: no orphan heading, no split table row.",
-    pptx: "16:9. One idea per slide, and the title is that idea as a sentence — a claim, not a label. " +
-        "At most six lines of body per slide, one figure per slide at most, and everything you cut " +
-        "goes into the speaker notes. Close on decisions and next steps, not on 'thank you'.",
-    docx: "Real Word styles for headings rather than manual bold, a table-of-contents field rather " +
-        "than a typed list, a header row on every table, and captions on figures.",
-    md: "A title heading, ATX headings throughout, tables for comparisons, fenced code with a language tag, and no HTML.",
-};
-function mergeGroup(base, over) {
-    if (!base)
-        return over;
-    if (!over)
-        return base;
-    return { ...base, ...over };
-}
-export function mergeDesign(base, over) {
-    if (!over)
-        return base;
-    return {
-        ...base,
-        ...over,
-        fonts: mergeGroup(base.fonts, over.fonts),
-        palette: mergeGroup(base.palette, over.palette),
-        rules: [...(base.rules ?? []), ...(over.rules ?? [])],
-    };
-}
-const line = (label, value) => (value ? [`${label}: ${value}`] : []);
-export function renderDesign(guide, format, notes) {
-    const { fonts, palette } = guide;
-    const parts = [
-        ...line("Style", guide.name),
-        ...line("Typefaces", [
-            fonts?.heading && `headings ${fonts.heading}`,
-            fonts?.body && `body ${fonts.body}`,
-            fonts?.mono && `code ${fonts.mono}`,
-        ]
-            .filter(Boolean)
-            .join(", ") || undefined),
-        ...line("Palette", [
-            palette?.primary && `primary ${palette.primary}`,
-            palette?.accent && `accent ${palette.accent}`,
-            palette?.text && `text ${palette.text}`,
-            palette?.muted && `muted ${palette.muted}`,
-            palette?.surface && `surface ${palette.surface}`,
-        ]
-            .filter(Boolean)
-            .join(", ") || undefined),
-        ...line("Layout", guide.layout),
-        ...line("Figures", guide.charts),
-        ...line("Voice", guide.tone),
-        ...line("Logo", guide.logoUrl),
-        `Format craft (.${format}): ${FORMAT_CRAFT[format]}`,
-        ...(guide.rules?.length ? [`Rules:\n${guide.rules.map((r) => `- ${r}`).join("\n")}`] : []),
-        ...(notes?.trim()
-            ? [`Overrides for this document, which win over everything above:\n${notes.trim()}`]
-            : []),
-    ];
-    return parts.join("\n");
-}
+const c={name:"Spendgraph house style",fonts:{heading:"Inter",body:"Inter",mono:"JetBrains Mono"},palette:{primary:"#0F172A",accent:"#2563EB",text:"#111827",muted:"#64748B",surface:"#FFFFFF"},layout:"A4 portrait, 20mm margins, a single text column at 60-75 characters, a 4pt spacing scale, and one heading scale used consistently (28/20/16/12). Whitespace is the design.",charts:"One message per figure, stated in its caption. Label series directly where there are three or fewer. No 3D, no gradients, no gridline heavier than the data, no pie chart past three slices, and axes that start at zero unless the caption says why not.",tone:"Plain and specific. Lead with the finding, then the evidence. No filler adjectives, no throat-clearing, no sentence that survives being deleted.",rules:["A cover carrying the title, date and author, and no other ornament.","Every number traceable to something in the source material; invent nothing.","Tables for anything being compared; prose for anything being argued.","No stock imagery, no clip art, no placeholder text in the finished file.","Page numbers on every page after the cover."]},d={pdf:"Cover, then contents if it runs past four pages, then the body. Figures captioned and referenced from the text. Nothing straddles a page break: no orphan heading, no split table row.",pptx:"16:9. One idea per slide, and the title is that idea as a sentence \u2014 a claim, not a label. At most six lines of body per slide, one figure per slide at most, and everything you cut goes into the speaker notes. Close on decisions and next steps, not on 'thank you'.",docx:"Real Word styles for headings rather than manual bold, a table-of-contents field rather than a typed list, a header row on every table, and captions on figures.",md:"A title heading, ATX headings throughout, tables for comparisons, fenced code with a language tag, and no HTML."};function i(e,t){return e?t?{...e,...t}:e:t}function h(e,t){return t?{...e,...t,fonts:i(e.fonts,t.fonts),palette:i(e.palette,t.palette),rules:[...e.rules??[],...t.rules??[]]}:e}const a=(e,t)=>t?[`${e}: ${t}`]:[];function p(e,t,o){const{fonts:r,palette:n}=e;return[...a("Style",e.name),...a("Typefaces",[r?.heading&&`headings ${r.heading}`,r?.body&&`body ${r.body}`,r?.mono&&`code ${r.mono}`].filter(Boolean).join(", ")||void 0),...a("Palette",[n?.primary&&`primary ${n.primary}`,n?.accent&&`accent ${n.accent}`,n?.text&&`text ${n.text}`,n?.muted&&`muted ${n.muted}`,n?.surface&&`surface ${n.surface}`].filter(Boolean).join(", ")||void 0),...a("Layout",e.layout),...a("Figures",e.charts),...a("Voice",e.tone),...a("Logo",e.logoUrl),`Format craft (.${t}): ${d[t]}`,...e.rules?.length?[`Rules:
+${e.rules.map(s=>`- ${s}`).join(`
+`)}`]:[],...o?.trim()?[`Overrides for this document, which win over everything above:
+${o.trim()}`]:[]].join(`
+`)}export{c as DEFAULT_DESIGN,h as mergeDesign,p as renderDesign};

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

@@ -1,71 +1 @@
-export const MOA_BASE_URL = "https://api.fnmoa.com";
-const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
-const ERROR_DETAIL_CHARS = 500;
-export class MoaApiError extends Error {
-    status;
-    detail;
-    constructor(message, status, detail) {
-        super(detail ? `${message}: ${detail}` : message);
-        this.name = "MoaApiError";
-        this.status = status;
-        this.detail = detail;
-    }
-}
-function reasonOf(err) {
-    const cause = err.cause;
-    return cause?.code ?? cause?.message ?? err.message;
-}
-function deadlineSignal(timeoutMs, caller) {
-    const controller = new AbortController();
-    const stop = () => controller.abort();
-    let expired = false;
-    const timer = setTimeout(() => {
-        expired = true;
-        stop();
-    }, timeoutMs);
-    caller?.addEventListener("abort", stop, { once: true });
-    if (caller?.aborted)
-        stop();
-    return {
-        signal: controller.signal,
-        expired: () => expired,
-        release: () => {
-            clearTimeout(timer);
-            caller?.removeEventListener("abort", stop);
-        },
-    };
-}
-export function createRequest(config = {}) {
-    const doFetch = config.fetch ?? globalThis.fetch.bind(globalThis);
-    const base = (config.baseUrl ?? MOA_BASE_URL).replace(/\/+$/, "");
-    return async function request(path, opts = {}) {
-        const timeoutMs = opts.timeoutMs ?? config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-        const method = opts.method ?? "GET";
-        const url = `${base}${path}`;
-        const { signal, expired, release } = deadlineSignal(timeoutMs, opts.signal);
-        try {
-            const res = await doFetch(url, {
-                method,
-                signal,
-                headers: {
-                    ...(config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}),
-                    ...(opts.body === undefined ? {} : { "content-type": "application/json" }),
-                },
-                ...(opts.body === undefined ? {} : { body: JSON.stringify(opts.body) }),
-            }).catch((err) => {
-                if (opts.signal?.aborted)
-                    throw err;
-                if (expired())
-                    throw new MoaApiError(`Moa did not answer ${method} ${path}`, 504, `${timeoutMs}ms`);
-                throw new MoaApiError(`Moa is unreachable at ${url}`, 0, reasonOf(err));
-            });
-            if (!res.ok) {
-                throw new MoaApiError(`Moa returned ${res.status} for ${method} ${path}`, res.status, (await res.text()).slice(0, ERROR_DETAIL_CHARS));
-            }
-            return res.status === 204 ? undefined : (await res.json());
-        }
-        finally {
-            release();
-        }
-    };
-}
+const f="https://api.fnmoa.com",M=6e4,_=500;class c extends Error{status;detail;constructor(t,s,n){super(n?`${t}: ${n}`:t),this.name="MoaApiError",this.status=s,this.detail=n}}function T(e){const t=e.cause;return t?.code??t?.message??e.message}function m(e,t){const s=new AbortController,n=()=>s.abort();let r=!1;const o=setTimeout(()=>{r=!0,n()},e);return t?.addEventListener("abort",n,{once:!0}),t?.aborted&&n(),{signal:s.signal,expired:()=>r,release:()=>{clearTimeout(o),t?.removeEventListener("abort",n)}}}function $(e={}){const t=e.fetch??globalThis.fetch.bind(globalThis),s=(e.baseUrl??f).replace(/\/+$/,"");return async function(r,o={}){const u=o.timeoutMs??e.timeoutMs??6e4,i=o.method??"GET",d=`${s}${r}`,{signal:E,expired:h,release:b}=m(u,o.signal);try{const a=await t(d,{method:i,signal:E,headers:{...e.apiKey?{authorization:`Bearer ${e.apiKey}`}:{},...o.body===void 0?{}:{"content-type":"application/json"}},...o.body===void 0?{}:{body:JSON.stringify(o.body)}}).catch(l=>{throw o.signal?.aborted?l:h()?new c(`Moa did not answer ${i} ${r}`,504,`${u}ms`):new c(`Moa is unreachable at ${d}`,0,T(l))});if(!a.ok)throw new c(`Moa returned ${a.status} for ${i} ${r}`,a.status,(await a.text()).slice(0,500));return a.status===204?void 0:await a.json()}finally{b()}}}export{f as MOA_BASE_URL,c as MoaApiError,$ as createRequest};

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

@@ -1,4 +1 @@
-export { CommissionAbortedError, CommissionTimeoutError, createCommissionClient, INTERACTIVE_TIMEOUT_MS, pollUntilDone, } from "./commission.js";
-export { DEFAULT_DESIGN, mergeDesign, renderDesign } from "./design.js";
-export { MOA_BASE_URL, MoaApiError } from "./http.js";
-export { writeDocument } from "./write-document.js";
+import{CommissionAbortedError as e,CommissionTimeoutError as i,createCommissionClient as m,INTERACTIVE_TIMEOUT_MS as t,pollUntilDone as n}from"./commission.js";import{DEFAULT_DESIGN as s,mergeDesign as p,renderDesign as A}from"./design.js";import{MOA_BASE_URL as T,MoaApiError as C}from"./http.js";import{writeDocument as f}from"./write-document.js";export{e as CommissionAbortedError,i as CommissionTimeoutError,s as DEFAULT_DESIGN,t as INTERACTIVE_TIMEOUT_MS,T as MOA_BASE_URL,C as MoaApiError,m as createCommissionClient,p as mergeDesign,n as pollUntilDone,A as renderDesign,f as writeDocument};

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

@@ -1 +0,0 @@
-export {};

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

@@ -1,142 +1 @@
-import { tool } from "../../tool/index.js";
-import { CommissionAbortedError, CommissionTimeoutError, createCommissionClient, pollUntilDone, } from "./commission.js";
-import { DEFAULT_DESIGN, mergeDesign, renderDesign } from "./design.js";
-const ALL_FORMATS = ["pdf", "pptx", "docx", "md"];
-const DEFAULT_TIMEOUT_MS = 600_000;
-const DEFAULT_SETTLE_MS = 2_000;
-const DEFAULT_MAX_CHARS = 4_000;
-function describe(formats, design) {
-    return ("Commissions a document agent to write and render a finished file — " +
-        `${formats.map((f) => `.${f}`).join(", ")} — and hands back where to download it. Use it ` +
-        "when the answer has to be a document somebody opens: a report, a deck, a proposal, a " +
-        "one-pager. Not for text you can simply write in your reply. It runs for minutes and it " +
-        `costs money, so brief it once and brief it fully — the agent cannot see this ` +
-        "conversation, so every fact, figure and quote it must use goes in `source`. Design is " +
-        `already settled by ${design.name ?? "the house style"}; use \`design_notes\` only for what ` +
-        "this one document must do differently.");
-}
-function delivered(result, style, maxChars, includeData) {
-    const documents = (result.artifacts ?? []).map((a) => ({
-        name: a.name,
-        format: a.format,
-        url: a.url,
-        mime: a.mime,
-        sizeBytes: a.sizeBytes,
-        ...(includeData && a.data ? { data: a.data } : {}),
-    }));
-    return {
-        taskId: result.id,
-        sessionId: result.sessionId,
-        status: "done",
-        style,
-        documents,
-        delivered: documents.length > 0,
-        writeUp: result.output?.slice(0, maxChars),
-        truncated: (result.output?.length ?? 0) > maxChars,
-        turns: result.numTurns,
-        costMicroUsd: result.costUsd === undefined ? undefined : Math.round(result.costUsd * 1_000_000),
-    };
-}
-function stillRendering(id, style, err) {
-    return {
-        taskId: id,
-        status: "running",
-        style,
-        documents: [],
-        delivered: false,
-        note: `Still rendering after ${Math.round(err.timeoutMs / 1000)}s. The task is not lost — ` +
-            "say so rather than commissioning it again.",
-    };
-}
-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.");
-    }
-    const allowed = opts.formats?.length ? opts.formats : ALL_FORMATS;
-    const design = mergeDesign(DEFAULT_DESIGN, opts.design);
-    const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
-    const client = opts.client ??
-        createCommissionClient({
-            apiKey: opts.apiKey,
-            baseUrl: opts.baseUrl,
-            ...(opts.fetch ? { fetch: opts.fetch } : {}),
-        });
-    return tool({
-        name: "write_document",
-        description: describe(allowed, design),
-        effect: "destructive",
-        args: [
-            {
-                name: "brief",
-                type: "text",
-                required: true,
-                maxLength: 8000,
-                description: "What to produce, who reads it, what it must cover and how long it runs. Write it " +
-                    "as you would brief a person who knows the craft and nothing about this account.",
-            },
-            {
-                name: "format",
-                type: "enum",
-                required: true,
-                options: ["pdf", "pptx", "docx", "md"],
-                description: "pptx for anything presented, pdf for anything sent, docx for anything edited.",
-            },
-            {
-                name: "source",
-                type: "text",
-                required: false,
-                maxLength: 40000,
-                description: "The material it must build from — figures, findings, quotes, an outline — verbatim. " +
-                    "Anything missing here the agent will either omit or invent.",
-            },
-            {
-                name: "design_notes",
-                type: "text",
-                required: false,
-                maxLength: 2000,
-                description: "How this one document departs from the house style, in plain words. Leave it empty " +
-                    "unless the user asked for something specific.",
-            },
-            {
-                name: "session_id",
-                type: "string",
-                required: false,
-                description: "Continue an earlier write_document instead of starting over — take it from that " +
-                    "result's sessionId. Use it to revise a document or to recast one into another format.",
-            },
-        ],
-        run: async ({ brief, format, source, design_notes, session_id }) => {
-            if (!allowed.includes(format)) {
-                throw new Error(`write_document was asked for .${format}, which this deployment does not produce ` +
-                    `(${allowed.map((f) => `.${f}`).join(", ")}).`);
-            }
-            const id = await client.create({
-                task: brief,
-                context: source,
-                design: renderDesign(design, format, design_notes),
-                artifacts: [format],
-                ...(session_id ? { sessionId: session_id } : {}),
-            });
-            try {
-                const result = await pollUntilDone(client, id, {
-                    timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-                    settleMs: DEFAULT_SETTLE_MS,
-                    expectArtifacts: true,
-                    ...(opts.signal ? { signal: opts.signal } : {}),
-                });
-                if (result.status === "failed") {
-                    throw new Error(`write_document: Moa task ${id} failed: ${result.error ?? "no reason given"}`);
-                }
-                return delivered(result, design.name, maxChars, opts.includeData === true);
-            }
-            catch (err) {
-                if (err instanceof CommissionAbortedError && opts.cancelOnAbort !== false) {
-                    await client.cancel?.(id).catch(() => undefined);
-                }
-                if (err instanceof CommissionTimeoutError)
-                    return stillRendering(id, design.name, err);
-                throw err;
-            }
-        },
-    });
-}
+import{tool as f}from"../../tool/index.js";import{CommissionAbortedError as l,CommissionTimeoutError as h,createCommissionClient as g,pollUntilDone as p}from"./commission.js";import{DEFAULT_DESIGN as w,mergeDesign as y,renderDesign as _}from"./design.js";const x=["pdf","pptx","docx","md"],b=6e5,M=2e3,U=4e3;function v(e,i){return`Commissions a document agent to write and render a finished file \u2014 ${e.map(t=>`.${t}`).join(", ")} \u2014 and hands back where to download it. Use it when the answer has to be a document somebody opens: a report, a deck, a proposal, a one-pager. Not for text you can simply write in your reply. It runs for minutes and it costs money, so brief it once and brief it fully \u2014 the agent cannot see this conversation, so every fact, figure and quote it must use goes in \`source\`. Design is already settled by ${i.name??"the house style"}; use \`design_notes\` only for what this one document must do differently.`}function E(e,i,t,d){const r=(e.artifacts??[]).map(o=>({name:o.name,format:o.format,url:o.url,mime:o.mime,sizeBytes:o.sizeBytes,...d&&o.data?{data:o.data}:{}}));return{taskId:e.id,sessionId:e.sessionId,status:"done",style:i,documents:r,delivered:r.length>0,writeUp:e.output?.slice(0,t),truncated:(e.output?.length??0)>t,turns:e.numTurns,costMicroUsd:e.costUsd===void 0?void 0:Math.round(e.costUsd*1e6)}}function T(e,i,t){return{taskId:e,status:"running",style:i,documents:[],delivered:!1,note:`Still rendering after ${Math.round(t.timeoutMs/1e3)}s. The task is not lost \u2014 say so rather than commissioning it again.`}}function L(e){if(!e.client&&!e.apiKey?.trim())throw new Error("writeDocument needs a Moa apiKey; it will not read one from the process.");const i=e.formats?.length?e.formats:x,t=y(w,e.design),d=e.maxChars??U,r=e.client??g({apiKey:e.apiKey,baseUrl:e.baseUrl,...e.fetch?{fetch:e.fetch}:{}});return f({name:"write_document",description:v(i,t),effect:"destructive",args:[{name:"brief",type:"text",required:!0,maxLength:8e3,description:"What to produce, who reads it, what it must cover and how long it runs. Write it as you would brief a person who knows the craft and nothing about this account."},{name:"format",type:"enum",required:!0,options:["pdf","pptx","docx","md"],description:"pptx for anything presented, pdf for anything sent, docx for anything edited."},{name:"source",type:"text",required:!1,maxLength:4e4,description:"The material it must build from \u2014 figures, findings, quotes, an outline \u2014 verbatim. Anything missing here the agent will either omit or invent."},{name:"design_notes",type:"text",required:!1,maxLength:2e3,description:"How this one document departs from the house style, in plain words. Leave it empty unless the user asked for something specific."},{name:"session_id",type:"string",required:!1,description:"Continue an earlier write_document instead of starting over \u2014 take it from that result's sessionId. Use it to revise a document or to recast one into another format."}],run:async({brief:o,format:s,source:u,design_notes:m,session_id:c})=>{if(!i.includes(s))throw new Error(`write_document was asked for .${s}, which this deployment does not produce (${i.map(n=>`.${n}`).join(", ")}).`);const a=await r.create({task:o,context:u,design:_(t,s,m),artifacts:[s],...c?{sessionId:c}:{}});try{const n=await p(r,a,{timeoutMs:e.timeoutMs??b,settleMs:M,expectArtifacts:!0,...e.signal?{signal:e.signal}:{}});if(n.status==="failed")throw new Error(`write_document: Moa task ${a} failed: ${n.error??"no reason given"}`);return E(n,t.name,d,e.includeData===!0)}catch(n){if(n instanceof l&&e.cancelOnAbort!==!1&&await r.cancel?.(a).catch(()=>{}),n instanceof h)return T(a,t.name,n);throw n}}})}export{L as writeDocument};

package/dist/bus/args.d.ts

@@ -0,0 +1,11 @@
+import type { ArgSpec } from "../types/index.js";
+/**
+ * The arguments a handler is given: declared defaults filled in, and every
+ * declared value at its declared type.
+ *
+ * Validation runs before this and on the raw arguments, so what is required
+ * stays required — a `default` fills a gap, it does not satisfy a demand.
+ * Anything the tool did not declare is passed through untouched: the model may
+ * have sent it, and dropping it would be this package deciding it knows better.
+ */
+export declare function readyArgs(specs: readonly ArgSpec[], args: Record<string, unknown>): Record<string, unknown>;

package/dist/bus/args.js

@@ -0,0 +1 @@
+import{isMissing as s,toBoolean as c,toNumber as f}from"@spendgraph/sdk";function i(e,n){switch(e.type){case"number":return f(n);case"boolean":return c(n);case"list":return Array.isArray(n)?n.map(String):n;case"json":return n;default:return String(n)}}function a(e,n){const t={...n};for(const r of e){const o=t[r.name];if(s(o)){if(r.default===void 0)continue;t[r.name]=i(r,r.default);continue}t[r.name]=i(r,o)}return t}export{a as readyArgs};

package/dist/bus/bus.js

@@ -1,49 +1 @@
-import { toAnthropic, toMarkdown, toOpenAI, } from "../wire/index.js";
-import { invokeTool } from "./invoke.js";
-import { warnOnOverlap } from "./overlap.js";
-import { selectTools } from "./select.js";
-import { toStep } from "./step.js";
-import { newTrace } from "./trace.js";
-export function toolbus(tools, opts = {}) {
-    const now = opts.now ?? (() => Date.now());
-    const ceiling = Math.max(1, opts.limit ?? 6);
-    const byName = new Map();
-    for (const t of tools) {
-        if (byName.has(t.name))
-            throw new Error(`Two tools are called "${t.name}".`);
-        byName.set(t.name, t);
-    }
-    const calls = new Map();
-    if (opts.warnOnOverlap ?? true)
-        warnOnOverlap([...byName.values()]);
-    const declare = (t) => ({
-        name: t.name,
-        description: t.description,
-        args: t.args,
-        ...(t.effect ? { effect: t.effect } : {}),
-    });
-    const all = () => [...byName.values()].map(declare);
-    const bus = {
-        all: () => [...byName.values()],
-        missing: (names) => names.filter((n) => !byName.has(n)),
-        get: (name) => byName.get(name),
-        effectOf: (name) => byName.get(name)?.effect,
-        destructive: () => [...byName.values()].filter((t) => t.effect === "destructive").map((t) => t.name),
-        unannotated: () => [...byName.values()].filter((t) => t.effect === undefined).map((t) => t.name),
-        declarations: (names) => names
-            ? names
-                .map((n) => byName.get(n))
-                .filter(Boolean)
-                .map((t) => declare(t))
-            : all(),
-        anthropic: (decls) => toAnthropic(decls ?? all()),
-        openai: (decls) => toOpenAI(decls ?? all()),
-        markdown: (decls, heading) => toMarkdown(decls ?? all(), heading),
-        select: (query = "", limit) => selectTools([...byName.values()], calls, declare, query, Math.max(1, limit ?? ceiling)),
-        invoke: (name, args) => invokeTool(byName, calls, now, name, args),
-        usage: () => Object.fromEntries(calls),
-        step: (result, index) => toStep(result, index),
-        trace: (query = "", limit) => newTrace(bus.select(query, limit), (name, args) => bus.invoke(name, args)),
-    };
-    return bus;
-}
+import{toAnthropic as w,toMarkdown as d,toOpenAI as g}from"../wire/index.js";import{invokeTool as O}from"./invoke.js";import{warnOnOverlap as h}from"./overlap.js";import{scorerFor as k}from"./score.js";import{selectTools as b}from"./select.js";import{toStep as T}from"./step.js";import{ceilingFor as l}from"./terms.js";import{newTrace as M}from"./trace.js";function I(c,a={}){const f=a.now??(()=>Date.now()),m=l(a.limit,6),t=new Map;for(const e of c){if(t.has(e.name))throw new Error(`Two tools are called "${e.name}".`);t.set(e.name,e)}const n=new Map;(a.warnOnOverlap??!0)&&h([...t.values()]);const p=k([...t.values()]),s=e=>({name:e.name,description:e.description,args:e.args,...e.aliases?.length?{aliases:e.aliases}:{},...e.effect?{effect:e.effect}:{}}),r=()=>[...t.values()].map(s),i={all:()=>[...t.values()],missing:e=>e.filter(o=>!t.has(o)),get:e=>t.get(e),effectOf:e=>t.get(e)?.effect,destructive:()=>[...t.values()].filter(e=>e.effect==="destructive").map(e=>e.name),unannotated:()=>[...t.values()].filter(e=>e.effect===void 0).map(e=>e.name),declarations:e=>e?e.map(o=>t.get(o)).filter(Boolean).map(o=>s(o)):r(),anthropic:e=>w(e??r()),openai:e=>g(e??r()),markdown:(e,o)=>d(e??r(),o),select:(e="",o)=>b([...t.values()],n,s,p,e,l(o,m)),invoke:(e,o)=>O(t,n,f,e,o),usage:()=>Object.fromEntries(n),step:(e,o)=>T(e,o),trace:(e="",o)=>M(i.select(e,o),(u,v)=>i.invoke(u,v))};return i}export{I as toolbus};

package/dist/bus/group.d.ts

@@ -0,0 +1,8 @@
+import type { ToolBus } from "./bus.js";
+import type { ToolBusOptions } from "./options.js";
+export interface BusMember {
+    name: string;
+    description: string;
+    bus: ToolBus;
+}
+export declare function busgroup(members: BusMember[], opts?: ToolBusOptions): ToolBus;

package/dist/bus/group.js

@@ -0,0 +1 @@
+import{toAnthropic as O,toMarkdown as I,toOpenAI as $}from"../wire/index.js";import{scorerFor as k}from"./score.js";import{toStep as A}from"./step.js";import{ceilingFor as M,termsIn as T}from"./terms.js";import{newTrace as x}from"./trace.js";const B=6,v=3;function D(t){return{name:t.name,description:t.description,args:[]}}function F(t){const s=new Map;for(const e of t)for(const o of e.bus.all()){const c=s.get(o.name);if(c)throw new Error(`Two buses offer a tool called "${o.name}": "${c.name}" and "${e.name}". A name has to say which one runs.`);s.set(o.name,e)}return s}function S(t){return t.flatMap(s=>{const e=s.bus.all().filter(o=>o.pinned).map(o=>o.name);return e.length>0?s.bus.declarations(e):[]})}function C(t){const s=[],e=new Set;let o=t;return{chosen:s,holds:c=>e.has(c),full:()=>s.length>=o,room:()=>t-s.length,narrowTo:c=>{o=Math.min(o,c)},take(c){e.has(c.name)||s.length>=o||(e.add(c.name),s.push(c))}}}function L(t,s,e){const o=t.flat(),c=k(o),f=o.map(l=>({declaration:l,n:c(l,s)})).sort((l,u)=>u.n-l.n);if(f.length===0||f[0].n===0)return!1;f.length>1&&f[0].n>=f[1].n*2&&e.narrowTo(e.chosen.length+v);for(const{declaration:l}of f){if(e.full())break;e.take(l)}return!0}function N(t,s){for(let e=0;!s.full();e++){let o=!1;for(const c of t){const f=c[e];if(f!==void 0&&(o=!0,s.take(f),s.full()))break}if(!o)break}}function z(t,s={}){const e=new Set;for(const n of t){if(e.has(n.name))throw new Error(`Two buses are called "${n.name}".`);e.add(n.name)}const o=F(t),c=S(t),f=new Map(t.map(n=>[n,D(n)])),m=k([...f.values()]),l=M(s.limit,B),u=n=>o.get(n),b=()=>t.flatMap(n=>n.bus.all()),p=()=>t.flatMap(n=>n.bus.declarations()),y=n=>t.map(a=>({member:a,n:m(f.get(a),n)})).sort((a,r)=>r.n-a.n),g={all:b,missing:n=>n.filter(a=>!o.has(a)),get:n=>u(n)?.bus.get(n),effectOf:n=>u(n)?.bus.effectOf(n),destructive:()=>t.flatMap(n=>n.bus.destructive()),unannotated:()=>t.flatMap(n=>n.bus.unannotated()),declarations:n=>n?t.flatMap(a=>{const r=n.filter(i=>o.get(i)===a);return r.length>0?a.bus.declarations(r):[]}):p(),anthropic:n=>O(n??p()),openai:n=>$(n??p()),markdown:(n,a)=>I(n??p(),a),select:(n="",a)=>{const r=C(M(a,l));for(const h of c)r.take(h);const i=r.room();if(i<=0)return r.chosen;const d=y(T(n)),w=d.map(({member:h})=>h.bus.select(n,i).filter(E=>!r.holds(E.name)));if(d.length>1&&d[0].n>0&&d[0].n>=d[1].n*2&&w[0].length>0){r.narrowTo(r.chosen.length+v);for(const h of w[0])r.take(h);return r.chosen}return L(w,T(n),r)||N(w,r),r.chosen},invoke:async(n,a)=>{const r=u(n);return r?r.bus.invoke(n,a):{name:n,args:a,status:"failed",output:"",error:`No tool called "${n}". Offered: ${[...o.keys()].join(", ")}`,latencyMs:0}},usage:()=>Object.assign({},...t.map(n=>n.bus.usage())),step:(n,a)=>A(n,a),trace:(n="",a)=>x(g.select(n,a),(r,i)=>g.invoke(r,i))};return g}export{z as busgroup};

package/dist/bus/index.d.ts

@@ -1,3 +1,4 @@
 export { type ToolBus, toolbus } from "./bus.js";
+export { type BusMember, busgroup } from "./group.js";
 export type { ToolBusOptions } from "./options.js";
 export { newTrace, type ToolTrace } from "./trace.js";

package/dist/bus/index.js

@@ -1,2 +1 @@
-export { toolbus } from "./bus.js";
-export { newTrace } from "./trace.js";
+import{toolbus as e}from"./bus.js";import{busgroup as t}from"./group.js";import{newTrace as m}from"./trace.js";export{t as busgroup,m as newTrace,e as toolbus};

package/dist/bus/invoke.js

@@ -1,43 +1 @@
-import { FieldValidationError, validateFields } from "@spendgraph/sdk";
-export async function invokeTool(byName, calls, now, name, args) {
-    const started = now();
-    const found = byName.get(name);
-    const base = { name, args, latencyMs: 0 };
-    if (!found) {
-        return {
-            ...base,
-            status: "failed",
-            output: "",
-            error: `No tool called "${name}". Offered: ${[...byName.keys()].join(", ")}`,
-        };
-    }
-    const errors = validateFields(args, found.args);
-    if (errors.length > 0) {
-        return {
-            ...base,
-            status: "failed",
-            output: "",
-            error: new FieldValidationError(errors).message,
-            latencyMs: now() - started,
-        };
-    }
-    calls.set(name, (calls.get(name) ?? 0) + 1);
-    try {
-        const value = await found.run(args);
-        return {
-            ...base,
-            status: "completed",
-            output: typeof value === "string" ? value : JSON.stringify(value),
-            latencyMs: now() - started,
-        };
-    }
-    catch (err) {
-        return {
-            ...base,
-            status: "failed",
-            output: "",
-            error: err instanceof Error ? err.message : "Tool failed.",
-            latencyMs: now() - started,
-        };
-    }
-}
+import{FieldValidationError as d,validateFields as f}from"@spendgraph/sdk";import{readyArgs as p}from"./args.js";import{reasonFor as y,render as g}from"./output.js";async function F(n,i,r,t,s){const a=r(),e=n.get(t),o={name:t,args:s,latencyMs:0};if(!e)return{...o,status:"failed",output:"",error:`No tool called "${t}". Offered: ${[...n.keys()].join(", ")}`};const l=f(s,e.args);if(l.length>0)return{...o,status:"failed",output:"",error:new d(l).message,latencyMs:r()-a};i.set(t,(i.get(t)??0)+1);const c=p(e.args,s);try{const u=await e.run(c);return{...o,status:"completed",output:g(u),latencyMs:r()-a}}catch(u){return{...o,status:"failed",output:"",error:y(u),latencyMs:r()-a}}}export{F as invokeTool};

package/dist/bus/options.js

@@ -1 +0,0 @@
-export {};

package/dist/bus/output.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What a handler returned, as the string a result carries.
+ *
+ * A string is itself; anything else is JSON. `graph`'s `stringify` describes
+ * this as "the same convention as a tool result" — it was not, and this is the
+ * side that had drifted.
+ *
+ * `JSON.stringify` returns `undefined` for a function or an undefined value, so
+ * a completed result carried `output: undefined` where its own type says
+ * `string`, and the model was handed nothing while being told it was handed
+ * something. And it *throws* on a circular object, a `BigInt`, or anything whose
+ * `toJSON` throws — a circular object being any value with a parent backlink.
+ *
+ * What comes back when a value cannot be written is a note saying so, never
+ * `""`: an empty output reads as a tool that produced nothing, and this is a
+ * tool that produced something unwritable.
+ */
+export declare function render(value: unknown): string;
+/**
+ * Why a handler failed, from whatever it threw.
+ *
+ * Anything can be thrown, and a string is thrown often enough. Reading only
+ * `Error.message` turned `throw "upstream refused"` into "Tool failed.", which
+ * discards the one thing the tool said about it.
+ */
+export declare function reasonFor(err: unknown): string;

package/dist/bus/output.js

@@ -0,0 +1,2 @@
+function r(n){if(n==null)return"";if(typeof n=="string")return n;try{const t=JSON.stringify(n);return t===void 0?`[not recordable: ${typeof n}]`:t}catch(t){return`[not recordable: ${(t instanceof Error?t.message:String(t)).split(`
+`)[0]}]`}}function o(n){if(n instanceof Error&&n.message.trim())return n.message;if(typeof n=="string"&&n.trim())return n;const t=r(n);return t&&t!=="{}"?`Tool failed: ${t}`:"Tool failed."}export{o as reasonFor,r as render};

package/dist/bus/overlap.js

@@ -1,31 +1 @@
-function words(tool) {
-    return new Set(tool.description
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((w) => w.length > 3));
-}
-export function warnOnOverlap(tools) {
-    const sets = tools.map(words);
-    const named = [];
-    let pairs = 0;
-    for (let i = 0; i < tools.length; i++) {
-        for (let j = i + 1; j < tools.length; j++) {
-            const a = sets[i];
-            const b = sets[j];
-            if (a.size === 0 || b.size === 0)
-                continue;
-            const shared = [...a].filter((w) => b.has(w)).length;
-            if (shared / Math.min(a.size, b.size) < 0.8)
-                continue;
-            pairs += 1;
-            if (named.length < 3)
-                named.push(`"${tools[i].name}" and "${tools[j].name}"`);
-        }
-    }
-    if (pairs === 0)
-        return;
-    const rest = pairs - named.length;
-    console.warn(`[toolbus] ${pairs} ${pairs === 1 ? "pair of tools describes" : "pairs of tools describe"} ` +
-        `themselves almost identically: ${named.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}. ` +
-        `The model will struggle to choose between them — give them distinct descriptions, or merge them.`);
-}
+import{termsIn as h}from"./terms.js";function m(e){return new Set(h(e.description).filter(i=>i.length>3))}function g(e){const i=e.map(m),s=[];let t=0;for(let n=0;n<e.length;n++)for(let r=n+1;r<e.length;r++){const o=i[n],l=i[r];o.size===0||l.size===0||[...o].filter(c=>l.has(c)).length/Math.min(o.size,l.size)<.8||(t+=1,s.length<3&&s.push(`"${e[n].name}" and "${e[r].name}"`))}if(t===0)return;const a=t-s.length;console.warn(`[toolbus] ${t} ${t===1?"pair of tools describes":"pairs of tools describe"} themselves almost identically: ${s.join(", ")}${a>0?`, and ${a} more`:""}. The model will struggle to choose between them \u2014 give them distinct descriptions, or merge them.`)}export{g as warnOnOverlap};

package/dist/bus/score.d.ts

@@ -1,9 +1,11 @@
-import type { Tool } from "../types/index.js";
-/**
- * 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 declare function score(tool: Tool<never>, terms: string[]): number;
+export interface Describable {
+    name: string;
+    description: string;
+    args: readonly {
+        name: string;
+        description?: string;
+    }[];
+    aliases?: readonly string[];
+}
+export type Scorer = (subject: Describable, terms: string[]) => number;
+export declare function scorerFor(corpus: readonly Describable[]): Scorer;

package/dist/bus/score.js

@@ -1,12 +1 @@
-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();
-    let n = 0;
-    for (const term of terms) {
-        if (name.includes(term))
-            n += 3;
-        else if (body.includes(term))
-            n += 1;
-    }
-    return n;
-}
+import{termsIn as l}from"./terms.js";const h=3,m=2,w=1,d=new WeakMap,a=n=>new Set(l(n));function g(n){const t=d.get(n);if(t)return t;const r={name:a(n.name.replace(/_/g," ")),aliases:a((n.aliases??[]).join(" ")),body:a(`${n.description} ${n.args.map(o=>`${o.name} ${o.description??""}`).join(" ")}`)};return d.set(n,r),r}function p(n,t){return n.name.has(t)?h:n.aliases.has(t)?m:n.body.has(t)?w:0}function I(n){const t=new Map;for(const o of n){const e=g(o);for(const s of new Set([...e.name,...e.aliases,...e.body]))t.set(s,(t.get(s)??0)+1)}const r=o=>Math.log((n.length+1)/((t.get(o)??0)+.5));return(o,e)=>{const s=g(o);let i=0;for(const c of e){const f=p(s,c);f>0&&(i+=f*r(c))}return i}}export{I as scorerFor};

package/dist/bus/select.d.ts

@@ -1,4 +1,5 @@
 import type { Tool, ToolDeclaration } from "../types/index.js";
+import type { Scorer } from "./score.js";
 /**
  * The working set for one request: pinned, then what the query matches, then
  * what actually gets used.
@@ -15,4 +16,4 @@ import type { Tool, ToolDeclaration } from "../types/index.js";
  * match needs no company; a flat spread means the ranking does not know, and a
  * wider net is worth the distraction.
  */
-export declare function selectTools(tools: Tool<never>[], calls: Map<string, number>, declare: (t: Tool<never>) => ToolDeclaration, query: string, ceiling: number): ToolDeclaration[];
+export declare function selectTools(tools: Tool<never>[], calls: Map<string, number>, declare: (t: Tool<never>) => ToolDeclaration, scoreOf: Scorer, query: string, ceiling: number): ToolDeclaration[];