@spendgraph/tools 0.2.0

package/dist/bus/overlap.js

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

package/dist/bus/score.d.ts

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

package/dist/bus/score.js

@@ -0,0 +1,19 @@
+/**
+ * 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();
+    let n = 0;
+    for (const term of terms) {
+        if (name.includes(term))
+            n += 3;
+        else if (body.includes(term))
+            n += 1;
+    }
+    return n;
+}

package/dist/bus/select.d.ts

@@ -0,0 +1,18 @@
+import type { Tool, ToolDeclaration } from "../types/index.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 declare function selectTools(tools: Tool<never>[], calls: Map<string, number>, declare: (t: Tool<never>) => ToolDeclaration, query: string, ceiling: number): ToolDeclaration[];

package/dist/bus/select.js

@@ -0,0 +1,71 @@
+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()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+    const chosen = [];
+    const take = (t) => {
+        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);
+    const rest = tools.filter((t) => !t.pinned);
+    const ranked = rest
+        .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);
+    for (const { t } of ranked) {
+        if (chosen.length >= budget)
+            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)
+            break;
+        if ((calls.get(t.name) ?? 0) === 0)
+            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)
+                break;
+            take(t);
+        }
+    }
+    return chosen.map(declare);
+}

package/dist/bus/step.d.ts

@@ -0,0 +1,4 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { ToolResult } from "../types/index.js";
+/** A result as a rollout step, for `report({ steps })`. */
+export declare function toStep(result: ToolResult, index: number): RolloutStep;

package/dist/bus/step.js

@@ -0,0 +1,12 @@
+/** A result as a rollout step, for `report({ steps })`. */
+export function toStep(result, index) {
+    return {
+        index,
+        source: result.name,
+        input: result.args,
+        output: result.output,
+        status: result.status,
+        error: result.error,
+        latencyMs: result.latencyMs,
+    };
+}

package/dist/bus/trace.d.ts

@@ -0,0 +1,42 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { Effect, ToolDeclaration, ToolResult } from "../types/index.js";
+import { type AnthropicTool, type OpenAITool } from "../wire/index.js";
+/**
+ * What one turn recorded: what was offered, and what was called.
+ *
+ * `record()` returns the pair in the shape `report()` takes, so the whole of the
+ * bookkeeping is `harness.report(id, { ...turn.record(), output, … })`.
+ */
+export interface ToolTrace {
+    /** The shortlist this turn was given, chosen once. */
+    offered: ToolDeclaration[];
+    anthropic(): AnthropicTool[];
+    openai(): OpenAITool[];
+    markdown(heading?: string): string;
+    /**
+     * What a tool offered this turn declared it does, or `undefined` for one that
+     * never said — and for one that was never offered.
+     */
+    effectOf(name: string): Effect | undefined;
+    /** Runs a tool and records the step. Never throws, exactly as `invoke`. */
+    invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /** The steps so far, in call order. */
+    steps(): RolloutStep[];
+    record(): {
+        offeredTools: string[];
+        steps: RolloutStep[];
+    };
+}
+/**
+ * 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 declare function newTrace(offered: ToolDeclaration[], invoke: (name: string, args: Record<string, unknown>) => Promise<ToolResult>): ToolTrace;

package/dist/bus/trace.js

@@ -0,0 +1,34 @@
+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 {
+        offered,
+        anthropic: () => toAnthropic(offered),
+        openai: () => toOpenAI(offered),
+        markdown: (heading) => toMarkdown(offered, heading),
+        effectOf: (name) => offered.find((d) => d.name === name)?.effect,
+        invoke: async (name, args) => {
+            const result = await invoke(name, args);
+            steps.push(toStep(result, steps.length));
+            return result;
+        },
+        steps: () => [...steps],
+        record: () => ({
+            offeredTools: offered.map((d) => d.name),
+            steps: [...steps],
+        }),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { type ArtifactFormat, answerOf, type ClockOptions, CommissionAbortedError, type CommissionClient, CommissionTimeoutError, calculate, currentTime, DEFAULT_DESIGN, type DeepRecallOptions, type DesignGuide, dateMath, deepRecall, type EscalateOptions, type EscalationRequest, escalate, type Finished, finish, type HttpOptions, httpRequest, isFinished, type JsonQueryOptions, jsonQuery, mergeDesign, renderDesign, type SearchDepth, think, type WebSearchOptions, type WriteDocumentOptions, webSearch, writeDocument, } from "./builtin/index.js";
+export type { ToolBus, ToolBusOptions, ToolTrace } from "./bus/index.js";
+export { toolbus } from "./bus/index.js";
+export type { BoundSpec, ToolSpec } from "./tool/index.js";
+export { bindTool, ToolDriftError, ToolNotStoredError, tool } from "./tool/index.js";
+export type { ArgSpec, ArgsOf, ArgValue, Effect, Tool, ToolDeclaration, ToolResult, } from "./types/index.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { answerOf, CommissionAbortedError, CommissionTimeoutError, calculate, currentTime, DEFAULT_DESIGN, dateMath, deepRecall, escalate, finish, httpRequest, isFinished, jsonQuery, mergeDesign, renderDesign, think, webSearch, writeDocument, } from "./builtin/index.js";
+export { toolbus } from "./bus/index.js";
+export { bindTool, ToolDriftError, ToolNotStoredError, tool } from "./tool/index.js";

package/dist/internals.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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, type Unit } from "./builtin/date/index.js";
+export { checkUrl } from "./builtin/http/index.js";
+export { readPath } from "./builtin/json/index.js";
+export { invokeTool } from "./bus/invoke.js";
+export { warnOnOverlap } from "./bus/overlap.js";
+export { score } from "./bus/score.js";
+export { selectTools } from "./bus/select.js";
+export { toStep } from "./bus/step.js";
+export { newTrace } from "./bus/trace.js";

package/dist/internals.js

@@ -0,0 +1,16 @@
+/**
+ * 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";
+export { readPath } from "./builtin/json/index.js";
+export { invokeTool } from "./bus/invoke.js";
+export { warnOnOverlap } from "./bus/overlap.js";
+export { score } from "./bus/score.js";
+export { selectTools } from "./bus/select.js";
+export { toStep } from "./bus/step.js";
+export { newTrace } from "./bus/trace.js";

package/dist/tool/bind.d.ts

@@ -0,0 +1,42 @@
+import type { Spendgraph } from "@spendgraph/sdk";
+import type { ArgSpec, ArgsOf, Tool } from "../types/index.js";
+/**
+ * A tool whose wording lives in the dashboard.
+ *
+ * No `description`: that is the half worth editing without a deploy, and having
+ * one here too would mean two sources for the string the model reads. The
+ * arguments stay in code because `run` is typed from them — pulling those would
+ * hand every handler a `Record<string, unknown>`.
+ */
+export interface BoundSpec<T extends readonly ArgSpec[]> {
+    name: string;
+    args: T;
+    run(args: ArgsOf<T>): Promise<unknown> | unknown;
+}
+/** The stored declaration disagrees with the one this code was written against. */
+export declare class ToolDriftError extends Error {
+    readonly toolName: string;
+    readonly differences: string[];
+    constructor(toolName: string, differences: string[]);
+}
+/** Nothing is stored under that name, so there is no wording to bind to. */
+export declare class ToolNotStoredError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
+/**
+ * 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 declare function bindTool<const T extends readonly ArgSpec[]>(sg: Spendgraph, spec: BoundSpec<T>, query?: {
+    project?: string;
+}): Promise<Tool<ArgsOf<T>>>;

package/dist/tool/bind.js

@@ -0,0 +1,89 @@
+import { tool } from "./tool.js";
+/** The stored declaration disagrees with the one this code was written against. */
+export class ToolDriftError extends Error {
+    toolName;
+    differences;
+    constructor(toolName, differences) {
+        super(`Tool "${toolName}" is stored differently from the code binding it: ${differences.join("; ")}.`);
+        this.toolName = toolName;
+        this.differences = differences;
+        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) {
+        super(`No stored tool named "${toolName}".`);
+        this.toolName = toolName;
+        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]));
+    for (const arg of declared) {
+        const found = byName.get(arg.name);
+        if (!found) {
+            out.push(`"${arg.name}" is declared here but not stored`);
+            continue;
+        }
+        byName.delete(arg.name);
+        if (found.type !== arg.type) {
+            out.push(`"${arg.name}" is ${arg.type} here and ${found.type} stored`);
+        }
+        if (found.required !== arg.required) {
+            out.push(`"${arg.name}" is ${arg.required ? "required" : "optional"} here and the reverse stored`);
+        }
+    }
+    for (const name of byName.keys()) {
+        out.push(`"${name}" is stored but not declared here`);
+    }
+    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);
+        }
+        throw err;
+    }
+    const differences = drift(spec.args, stored.args ?? []);
+    if (differences.length)
+        throw new ToolDriftError(spec.name, differences);
+    return tool({
+        name: stored.name,
+        description: stored.description,
+        args: spec.args,
+        effect: stored.effect ?? undefined,
+        pinned: stored.pinned,
+        run: spec.run,
+    });
+}

package/dist/tool/index.d.ts

@@ -0,0 +1,4 @@
+export type { BoundSpec } from "./bind.js";
+export { bindTool, ToolDriftError, ToolNotStoredError } from "./bind.js";
+export type { ToolSpec } from "./tool.js";
+export { tool } from "./tool.js";

package/dist/tool/index.js

@@ -0,0 +1,2 @@
+export { bindTool, ToolDriftError, ToolNotStoredError } from "./bind.js";
+export { tool } from "./tool.js";

package/dist/tool/tool.d.ts

@@ -0,0 +1,20 @@
+import type { ArgSpec, ArgsOf, Effect, Tool } from "../types/index.js";
+export interface ToolSpec<T extends readonly ArgSpec[]> {
+    name: string;
+    description: string;
+    args: T;
+    pinned?: boolean;
+    effect?: Effect;
+    run(args: ArgsOf<T>): Promise<unknown> | unknown;
+}
+/**
+ * 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 declare function tool<const T extends readonly ArgSpec[]>(spec: ToolSpec<T>): Tool<ArgsOf<T>>;

package/dist/tool/tool.js

@@ -0,0 +1,62 @@
+/** 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) {
+    if (!arg.options?.length) {
+        throw new Error(`Tool "${toolName}" argument "${arg.name}" is an enum with no options, so nothing can satisfy it.`);
+    }
+    const choices = new Set();
+    for (const option of arg.options) {
+        if (!option.trim()) {
+            throw new Error(`Tool "${toolName}" argument "${arg.name}" has a blank option, which the model can pick and you cannot act on.`);
+        }
+        if (choices.has(option)) {
+            throw new Error(`Tool "${toolName}" argument "${arg.name}" lists "${option}" twice.`);
+        }
+        choices.add(option);
+    }
+}
+function checkArgs(toolName, args) {
+    const seen = new Set();
+    for (const arg of args) {
+        if (!VALID_NAME.test(arg.name)) {
+            throw new Error(`Tool "${toolName}" argument "${arg.name}" is not a usable name.`);
+        }
+        if (seen.has(arg.name)) {
+            throw new Error(`Tool "${toolName}" declares "${arg.name}" twice.`);
+        }
+        seen.add(arg.name);
+        if (arg.type === "enum")
+            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.`);
+    }
+    if (!spec.description.trim()) {
+        throw new Error(`Tool "${spec.name}" has no description. It is the only thing the model reads to decide whether to call it.`);
+    }
+    checkArgs(spec.name, spec.args);
+    if (spec.effect !== undefined && !EFFECTS.includes(spec.effect)) {
+        throw new Error(`Tool "${spec.name}" declares effect "${spec.effect}", which is not one of ${EFFECTS.join(", ")}.`);
+    }
+    return {
+        name: spec.name,
+        description: spec.description,
+        args: spec.args.map((a) => ({ ...a, options: a.options ? [...a.options] : undefined })),
+        pinned: spec.pinned,
+        ...(spec.effect ? { effect: spec.effect } : {}),
+        run: spec.run,
+    };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export type { ToolResult } from "./result.js";
+export type { ArgSpec, ArgsOf, ArgValue, Effect, Tool, ToolDeclaration } from "./tool.js";

package/dist/types/index.js

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

package/dist/types/result.d.ts

@@ -0,0 +1,10 @@
+/** What happened when one was called. */
+export interface ToolResult {
+    name: string;
+    args: Record<string, unknown>;
+    status: "completed" | "failed";
+    /** Whatever `run` returned, stringified for the record. */
+    output: string;
+    error?: string;
+    latencyMs: number;
+}

package/dist/types/result.js

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

package/dist/types/tool.d.ts

@@ -0,0 +1,105 @@
+import type { FieldSpec, FieldType } from "@spendgraph/sdk";
+/**
+ * A declared argument, as written.
+ *
+ * Structurally a `FieldSpec` with every field readonly, because that is what an
+ * `as const` array produces — and `FieldSpec.options` being a mutable
+ * `string[]` is enough to make the whole tuple fail the constraint and inference
+ * fall back to nothing, silently.
+ */
+export interface ArgSpec {
+    readonly name: string;
+    readonly type: FieldType;
+    readonly required: boolean;
+    readonly default?: string;
+    readonly description?: string;
+    readonly options?: readonly string[];
+    readonly separator?: string;
+    readonly min?: number;
+    readonly max?: number;
+    readonly maxLength?: number;
+    readonly trueText?: string;
+    readonly falseText?: string;
+    readonly datasetKey?: boolean;
+}
+/** What one declared argument is worth at runtime. */
+export type ArgValue<F> = F extends {
+    type: "number";
+} ? number : F extends {
+    type: "boolean";
+} ? boolean : F extends {
+    type: "list";
+} ? string[] : F extends {
+    type: "json";
+} ? unknown : F extends {
+    type: "enum";
+    options: readonly (infer O)[];
+} ? O : string;
+type Required<T> = T extends {
+    required: true;
+} ? T : never;
+type Optional<T> = T extends {
+    required: true;
+} ? never : T;
+/**
+ * The object `run` is handed, derived from the args you declared.
+ *
+ * Declare `args` with `as const` and the handler's parameter types follow —
+ * a `number` arg arrives as a number, a missing optional is optional, and a
+ * renamed arg is a compile error at the handler rather than a runtime one
+ * mid-loop.
+ */
+export type ArgsOf<T extends readonly ArgSpec[]> = {
+    [F in Required<T[number]> as F["name"]]: ArgValue<F>;
+} & {
+    [F in Optional<T[number]> as F["name"]]?: ArgValue<F>;
+};
+/**
+ * What running a tool does to the world outside the process.
+ *
+ * `readonly` has no external effect. `idempotent` has one, but running it twice
+ * is the same as running it once. `destructive` is neither, so it is never safe
+ * to retry on its own.
+ *
+ * Three values rather than a taxonomy: anything finer does not get filled in
+ * accurately. There is no default — unset means nobody has said, which is not
+ * the same as safe.
+ */
+export type Effect = "readonly" | "idempotent" | "destructive";
+/**
+ * A description the model reads and a function you wrote, in one object.
+ *
+ * Splitting them — a schema here, a handler there, matched by string — is how a
+ * rename becomes a runtime failure mid-loop. Arguments are `FieldSpec` because a
+ * tool's arguments and a prompt's placeholders are the same problem.
+ */
+export interface Tool<Args = Record<string, unknown>> {
+    /** What the model calls it. Also the key it is registered under. */
+    name: string;
+    /**
+     * What the model reads to decide whether to call it, and the biggest lever on
+     * whether it calls it correctly. Worth iterating on more than the code is.
+     */
+    description: string;
+    args: FieldSpec[];
+    /**
+     * Offered whatever selection decides — an escalation path, a refusal, where
+     * losing a similarity search is not an acceptable outcome.
+     */
+    pinned?: boolean;
+    /** What calling it does outside the process. Unset means unknown. */
+    effect?: Effect;
+    run(args: Args): Promise<unknown> | unknown;
+}
+/** A tool as the model sees it: no implementation, no pin. */
+export interface ToolDeclaration {
+    name: string;
+    description: string;
+    args: FieldSpec[];
+    /**
+     * Carried so a caller can gate on it. Dropped by every provider shape — no
+     * API has a field for it, and an unknown key is rejected or ignored.
+     */
+    effect?: Effect;
+}
+export {};