@spendgraph/tools 0.2.0

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

@@ -0,0 +1,74 @@
+/** 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;
+    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);
+        },
+    };
+}
+/** 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(/\/+$/, "");
+    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();
+        }
+    };
+}

package/dist/builtin/write-document/index.d.ts

@@ -0,0 +1,6 @@
+export type { CommissionClient, PollOptions } from "./commission.js";
+export { CommissionAbortedError, CommissionTimeoutError, createCommissionClient, INTERACTIVE_TIMEOUT_MS, pollUntilDone, } from "./commission.js";
+export { DEFAULT_DESIGN, type DesignGuide, mergeDesign, renderDesign } from "./design.js";
+export { MOA_BASE_URL, MoaApiError, type MoaClientConfig } from "./http.js";
+export type { ArtifactFormat, CommissionArtifact, CommissionInput, CommissionResult, CommissionStatus, } from "./types.js";
+export { type WriteDocumentOptions, writeDocument } from "./write-document.js";

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

@@ -0,0 +1,4 @@
+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";

package/dist/builtin/write-document/types.d.ts

@@ -0,0 +1,33 @@
+/** A document format Moa can leave behind in `artifacts/`. */
+export type ArtifactFormat = "md" | "pdf" | "docx" | "pptx";
+/** Where a commission has got to. `pending` is queued, `failed` is settled. */
+export type CommissionStatus = "pending" | "running" | "done" | "failed";
+/** One finished file, either downloadable or carried inline as base64. */
+export interface CommissionArtifact {
+    name: string;
+    format: ArtifactFormat;
+    url?: string;
+    data?: string;
+    mime?: string;
+    sizeBytes?: number;
+}
+/** What to commission: the ask, the material it rests on, and the house style. */
+export interface CommissionInput {
+    task: string;
+    context?: string;
+    design?: string;
+    artifacts?: readonly ArtifactFormat[];
+    sessionId?: string;
+    newSessionId?: string;
+}
+/** A commission as it stands right now. */
+export interface CommissionResult {
+    id: string;
+    status: CommissionStatus;
+    output?: string;
+    error?: string;
+    costUsd?: number;
+    numTurns?: number;
+    sessionId?: string;
+    artifacts?: CommissionArtifact[];
+}

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

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

package/dist/builtin/write-document/write-document.d.ts

@@ -0,0 +1,69 @@
+import { type CommissionClient } from "./commission.js";
+import { type DesignGuide } from "./design.js";
+import type { AbortSignalLike } from "./http.js";
+import type { ArtifactFormat } from "./types.js";
+export interface WriteDocumentOptions {
+    /** Moa key. Required, and read from here rather than the environment. */
+    apiKey: string;
+    /** Defaults to `https://api.fnmoa.com`. */
+    baseUrl?: string;
+    /**
+     * House style laid over {@link DEFAULT_DESIGN}: named fields win, `rules`
+     * accumulate. This is where a brand goes, so the model cannot dilute it.
+     */
+    design?: DesignGuide;
+    /** Formats this deployment will produce. Default all four. */
+    formats?: readonly ArtifactFormat[];
+    /** Give up waiting after this. Default 600000 — rendering is minutes, not seconds. */
+    timeoutMs?: number;
+    /** Stops the wait. With `cancelOnAbort`, stops the task too. */
+    signal?: AbortSignalLike;
+    /** Cancel the task server-side when `signal` fires. Default true. */
+    cancelOnAbort?: boolean;
+    /** Return artifact bytes inline. Default false: base64 of a PDF is not context. */
+    includeData?: boolean;
+    /** Longest write-up handed back. Default 4000 characters. */
+    maxChars?: number;
+    /** Injected for tests, and for anyone fronting Moa with their own transport. */
+    client?: CommissionClient;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * 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 declare function writeDocument(opts: WriteDocumentOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "brief";
+    readonly type: "text";
+    readonly required: true;
+    readonly maxLength: 8000;
+    readonly description: string;
+}, {
+    readonly name: "format";
+    readonly type: "enum";
+    readonly required: true;
+    readonly options: readonly ["pdf", "pptx", "docx", "md"];
+    readonly description: "pptx for anything presented, pdf for anything sent, docx for anything edited.";
+}, {
+    readonly name: "source";
+    readonly type: "text";
+    readonly required: false;
+    readonly maxLength: 40000;
+    readonly description: string;
+}, {
+    readonly name: "design_notes";
+    readonly type: "text";
+    readonly required: false;
+    readonly maxLength: 2000;
+    readonly description: string;
+}, {
+    readonly name: "session_id";
+    readonly type: "string";
+    readonly required: false;
+    readonly description: string;
+}]>>;

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

@@ -0,0 +1,150 @@
+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.",
+    };
+}
+/**
+ * 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.");
+    }
+    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;
+            }
+        },
+    });
+}

package/dist/bus/bus.d.ts

@@ -0,0 +1,76 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { Effect, Tool, ToolDeclaration, ToolResult } from "../types/index.js";
+import { type AnthropicTool, type OpenAITool } from "../wire/index.js";
+import type { ToolBusOptions } from "./options.js";
+import { type ToolTrace } 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 declare function toolbus(tools: Tool<never>[], opts?: ToolBusOptions): {
+    /** Every tool, in declaration order. */
+    all: () => Tool<never>[];
+    /**
+     * 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: string[]) => string[];
+    get: (name: string) => Tool<never> | undefined;
+    /**
+     * 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: string) => Effect | undefined;
+    /**
+     * 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: () => string[];
+    /** Names of the tools with no effect declared, so a gate can refuse to guess. */
+    unannotated: () => string[];
+    /** Declarations for the model. Neutral shape; adapt per provider. */
+    declarations: (names?: string[]) => ToolDeclaration[];
+    /**
+     * 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?: ToolDeclaration[]) => AnthropicTool[];
+    /** Everything, in the shape the OpenAI chat completions API takes. */
+    openai: (decls?: ToolDeclaration[]) => OpenAITool[];
+    /**
+     * 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?: ToolDeclaration[], heading?: string) => string;
+    /** The working set for one request. */
+    select: (query?: string, limit?: number) => ToolDeclaration[];
+    /** Runs one, validating its arguments first. Never throws. */
+    invoke: (name: string, args: Record<string, unknown>) => Promise<ToolResult>;
+    /** How many times each has been called on this bus. */
+    usage: () => Record<string, number>;
+    /** A result as a rollout step, for `report({ steps })`. */
+    step: (result: ToolResult, index: number) => RolloutStep;
+    /** One turn's tool use, selected once and recorded for the rollout. */
+    trace: (query?: string, limit?: number) => ToolTrace;
+};
+export type ToolBus = ReturnType<typeof toolbus>;

package/dist/bus/bus.js

@@ -0,0 +1,103 @@
+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";
+/**
+ * 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);
+    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);
+    }
+    /** How often each has been called, so the useful ones stay offered. */
+    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 = {
+        /** 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/index.d.ts

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

package/dist/bus/index.js

@@ -0,0 +1,2 @@
+export { toolbus } from "./bus.js";
+export { newTrace } from "./trace.js";

package/dist/bus/invoke.d.ts

@@ -0,0 +1,9 @@
+import type { Tool, ToolResult } from "../types/index.js";
+/**
+ * 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 declare function invokeTool(byName: Map<string, Tool<never>>, calls: Map<string, number>, now: () => number, name: string, args: Record<string, unknown>): Promise<ToolResult>;

package/dist/bus/invoke.js

@@ -0,0 +1,50 @@
+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);
+    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,
+        };
+    }
+}

package/dist/bus/options.d.ts

@@ -0,0 +1,22 @@
+export interface ToolBusOptions {
+    /** Injectable clock, so tests do not measure real time. */
+    now?: () => number;
+    /**
+     * The most tools `select` will offer. Default 6.
+     *
+     * 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. They used to be added on top, so four pinned
+     * and a limit of six offered ten — which is the number that matters.
+     */
+    limit?: number;
+    /**
+     * Warn when two tools describe themselves almost identically. Default true.
+     *
+     * Nothing fails at runtime when they do; the model just picks wrong more
+     * often, which is why it is worth saying at construction.
+     */
+    warnOnOverlap?: boolean;
+}

package/dist/bus/options.js

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

package/dist/bus/overlap.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from "../types/index.js";
+/**
+ * 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 declare function warnOnOverlap(tools: Tool<never>[]): void;