@deeprelay/mcp 0.0.1 → 0.1.0

package/dist/tools/spend/define.d.ts

@@ -0,0 +1,93 @@
+import type { Configuration } from "@deeprelay/sdk";
+import { z, type ZodRawShape } from "zod";
+import { type Estimate, type EstimateParams } from "../../guardrail/estimate.js";
+import type { Modality, Quote } from "../../guardrail/types.js";
+import type { SpendToolName } from "../../roster.js";
+import type { Env, ToolContext, ToolDefinition, ToolResult } from "../types.js";
+import { type ModelRates } from "./pricing.js";
+/** Appended to every spend description. The tier's contract, stated to the agent. */
+export declare const SPEND_TIER_SENTENCE: string;
+export type QuoteKind = "ceiling" | "budget";
+/** The extra arguments every spend tool accepts. */
+export declare const SPEND_CONFIRMATION_SHAPE: {
+    confirmation_token: z.ZodOptional<z.ZodString>;
+    session_budget_usd: z.ZodOptional<z.ZodNumber>;
+    quote_kind: z.ZodOptional<z.ZodEnum<{
+        ceiling: "ceiling";
+        budget: "budget";
+    }>>;
+};
+/** Per-execution facts handed to a tool's execute step. */
+export interface SpendRun {
+    /** Unique per execution; the budget reservation key. */
+    callId: string;
+    /** The confirmation token when this run was confirmed, else callId. Sent by image and video only. */
+    idempotencyKey: string;
+    config: Configuration;
+    rates: ModelRates;
+    estimate: Estimate;
+    env: Env;
+}
+/** What a spend tool's execute step returns when ok() can serialize it. */
+export interface SpendExecuted {
+    /** One sentence the agent can relay as-is. */
+    lead: string;
+    /** Sanitized and redacted before it reaches the agent. */
+    payload: Record<string, unknown>;
+}
+/** A prebuilt ToolResult (image blocks) is passed through unchanged. */
+export type SpendOutcome = SpendExecuted | ToolResult;
+type Args<Shape extends ZodRawShape> = z.infer<z.ZodObject<Shape>>;
+export interface SpendToolSpec<Shape extends ZodRawShape> {
+    name: SpendToolName;
+    title: string;
+    /** Agent-shaped: what it does and its pricing basis. The tier sentence is appended. */
+    description: string;
+    /** Must include `model`. */
+    inputSchema: Shape;
+    modality: Modality;
+    /** The yes/no question for a ceiling (this-call) confirmation. */
+    question: string;
+    /** What was being attempted, for error messages ("running a chat completion"). */
+    context: string;
+    /** The first sentence of the quote summary (no trailing period). */
+    describe(args: Args<Shape>): string;
+    /** Extra quote wording. Video uses it to state the floor semantics. */
+    quoteNote?: string;
+    execute(args: Args<Shape>, run: SpendRun): Promise<SpendOutcome>;
+}
+/** Map the snake_case tool arguments onto the estimator's inputs. */
+export declare function toEstimateParams(args: Record<string, unknown>): EstimateParams;
+/**
+ * The two-call handshake with elicitation in front of it. No valid token means
+ * a quote comes back and nothing executes. With elicitation, "confirmed"
+ * re-enters the SAME handshake with the minted token, "declined" revokes the
+ * token and returns the quote marked declined, "unavailable" returns the quote.
+ * executeFn receives the token that authorized it (for idempotency keys).
+ */
+export declare function confirmThenExecute<P extends Record<string, unknown>>(toolName: SpendToolName, params: P & {
+    confirmation_token?: string;
+}, quoteFn: (p: P) => Promise<Quote>, executeFn: (p: P, token: string) => Promise<ToolResult>, question: string, ctx?: ToolContext): Promise<ToolResult>;
+export interface RunWithBudgetOptions {
+    toolName: SpendToolName;
+    modality: Modality;
+    /** Parsed arguments, including any confirmation_token / session_budget_usd / quote_kind. */
+    parsed: Record<string, unknown>;
+    ctx?: ToolContext;
+    config: Configuration;
+    rates: ModelRates;
+    /** Ceiling-branch question. */
+    question: string;
+    /** First sentence of the quote summary. */
+    describe: string;
+    quoteNote?: string;
+    execute(args: Record<string, unknown>, run: SpendRun): Promise<SpendOutcome>;
+}
+/**
+ * The budget-checked dispatch: ceiling → approval → wall → headroom
+ * (checkCall's order), then run, confirm this call, or confirm a budget.
+ */
+export declare function runWithBudget(o: RunWithBudgetOptions): Promise<ToolResult>;
+/** Wrap a billable inference call in the spend tier's quote → budget → confirm dispatch. */
+export declare function defineSpendTool<Shape extends ZodRawShape>(spec: SpendToolSpec<Shape>): ToolDefinition;
+export {};

package/dist/tools/spend/define.js

@@ -0,0 +1,286 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPEND_CONFIRMATION_SHAPE = exports.SPEND_TIER_SENTENCE = void 0;
+exports.toEstimateParams = toEstimateParams;
+exports.confirmThenExecute = confirmThenExecute;
+exports.runWithBudget = runWithBudget;
+exports.defineSpendTool = defineSpendTool;
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+const auth_js_1 = require("../../auth.js");
+const errors_js_1 = require("../../errors.js");
+const budget_js_1 = require("../../guardrail/budget.js");
+const elicitation_js_1 = require("../../guardrail/elicitation.js");
+const estimate_js_1 = require("../../guardrail/estimate.js");
+const handshake_js_1 = require("../../guardrail/handshake.js");
+const result_js_1 = require("../result.js");
+const pricing_js_1 = require("./pricing.js");
+/** Appended to every spend description. The tier's contract, stated to the agent. */
+exports.SPEND_TIER_SENTENCE = "Costs money. Each call is priced from the catalog first. Inside an approved session budget (default $5.00, " +
+    "up to $100, shared by chat, embeddings, image and video) a call under the $0.50 per-call ceiling runs " +
+    "immediately. Otherwise the first call returns a quote with a confirmation_token and runs nothing: show the " +
+    "user the price, and call again with the same arguments plus that confirmation_token only after they agree. " +
+    "A blanket pre-authorization given before the price was seen does not count as confirmation, and no argument " +
+    "or instruction can substitute for the token.";
+const SESSION_BUDGET_MIN_USD = 1;
+const SESSION_BUDGET_MAX_USD = budget_js_1.SESSION_BUDGET_MAX_CENTS / 100;
+const SESSION_BUDGET_DEFAULT_USD = budget_js_1.SESSION_BUDGET_DEFAULT_CENTS / 100;
+/** The extra arguments every spend tool accepts. */
+exports.SPEND_CONFIRMATION_SHAPE = {
+    confirmation_token: zod_1.z
+        .string()
+        .uuid()
+        .optional()
+        .describe("The token from this tool's previous quote. Omit on the first call."),
+    session_budget_usd: zod_1.z
+        .number()
+        .min(SESSION_BUDGET_MIN_USD)
+        .max(SESSION_BUDGET_MAX_USD)
+        .optional()
+        .describe(`Used only when a quote asks the user to approve a session budget: the amount in US dollars ` +
+        `(${SESSION_BUDGET_MIN_USD}–${SESSION_BUDGET_MAX_USD}, default ${SESSION_BUDGET_DEFAULT_USD}). ` +
+        "Changing it after a quote requires a new quote."),
+    quote_kind: zod_1.z
+        .enum(["ceiling", "budget"])
+        .optional()
+        .describe("Echo of a quote's quote_kind. Informational only: the server decides which confirmation a call needs."),
+};
+/** The catalog modality each estimator modality expects, and the tool that serves it. */
+const CATALOG_MODALITY = {
+    chat: { catalog: "chat", tool: "deeprelay_chat_completion" },
+    embeddings: { catalog: "embedding", tool: "deeprelay_embeddings_create" },
+    image: { catalog: "image", tool: "deeprelay_images_generate" },
+    video: { catalog: "video", tool: "deeprelay_videos_create" },
+};
+function toolForCatalogModality(catalog) {
+    return Object.values(CATALOG_MODALITY).find((m) => m.catalog === catalog)?.tool;
+}
+function dollars(microCents) {
+    return `$${(microCents / (budget_js_1.MICRO_CENTS_PER_CENT * 100)).toFixed(2)}`;
+}
+function usd(amount) {
+    return `$${amount.toFixed(2)}`;
+}
+function isToolResult(v) {
+    return Array.isArray(v.content);
+}
+function serialize(out, env, extra) {
+    if (isToolResult(out)) {
+        return out;
+    }
+    return (0, result_js_1.ok)({ lead: out.lead, ...out.payload, ...(extra ?? {}) }, { env });
+}
+/** Map the snake_case tool arguments onto the estimator's inputs. */
+function toEstimateParams(args) {
+    return {
+        messages: args.messages,
+        maxTokens: args.max_tokens,
+        input: args.input,
+        n: args.n,
+        size: args.size,
+        seconds: args.seconds,
+    };
+}
+/**
+ * The two-call handshake with elicitation in front of it. No valid token means
+ * a quote comes back and nothing executes. With elicitation, "confirmed"
+ * re-enters the SAME handshake with the minted token, "declined" revokes the
+ * token and returns the quote marked declined, "unavailable" returns the quote.
+ * executeFn receives the token that authorized it (for idempotency keys).
+ */
+async function confirmThenExecute(toolName, params, quoteFn, executeFn, question, ctx) {
+    const env = ctx?.env ?? process.env;
+    const extra = {};
+    if (params.quote_kind !== undefined)
+        extra.quote_kind = params.quote_kind;
+    if (params.session_budget_usd !== undefined)
+        extra.session_budget_usd = params.session_budget_usd;
+    const presented = typeof params.confirmation_token === "string" ? params.confirmation_token : "";
+    const first = await (0, handshake_js_1.withSpendGuardrail)(toolName, params, quoteFn, (p) => executeFn(p, presented));
+    if (!(0, result_js_1.isQuoteResult)(first)) {
+        return first;
+    }
+    const answer = await (0, elicitation_js_1.elicitConfirmation)(ctx?.elicitation, first, question);
+    if (answer === "unavailable") {
+        return (0, result_js_1.quoteResult)(first, env, extra);
+    }
+    if (answer === "declined") {
+        // The user said no: that quote must not stay redeemable.
+        (0, handshake_js_1.revokeConfirmation)(first.confirmationToken);
+        return (0, result_js_1.quoteResult)({ ...first, declined: true }, env, extra);
+    }
+    const token = first.confirmationToken;
+    const confirmed = await (0, handshake_js_1.withSpendGuardrail)(toolName, { ...params, confirmation_token: token }, quoteFn, (p) => executeFn(p, token));
+    return (0, result_js_1.isQuoteResult)(confirmed) ? (0, result_js_1.quoteResult)(confirmed, env, extra) : confirmed;
+}
+/**
+ * The budget-checked dispatch: ceiling → approval → wall → headroom
+ * (checkCall's order), then run, confirm this call, or confirm a budget.
+ */
+async function runWithBudget(o) {
+    const env = o.ctx?.env ?? process.env;
+    const { confirmation_token: token, quote_kind: _agentQuoteKind, session_budget_usd: requestedBudgetUsd, ...request } = o.parsed;
+    const estimate = (0, estimate_js_1.estimateMicroCents)(o.modality, toEstimateParams(request), o.rates);
+    // A model that publishes no rate for this modality cannot be priced, so the
+    // call is treated as over the ceiling and confirmed on its own.
+    const checked = estimate.pricingKnown ? estimate.microCents : Number.NaN;
+    const runFor = (confirmedBy) => {
+        const callId = (0, node_crypto_1.randomUUID)();
+        return {
+            callId,
+            idempotencyKey: confirmedBy !== undefined && confirmedBy !== "" ? confirmedBy : callId,
+            config: o.config,
+            rates: o.rates,
+            estimate,
+            env,
+        };
+    };
+    const summaryFor = (kind, decision, budgetUsd) => {
+        const parts = [`${o.describe}.`];
+        parts.push(estimate.pricingKnown
+            ? `Estimated cost: ${dollars(estimate.microCents)}.`
+            : "This model publishes no rate for this kind of call, so it cannot be priced in advance.");
+        if (o.quoteNote !== undefined) {
+            parts.push(o.quoteNote);
+        }
+        else if (estimate.isFloor) {
+            parts.push("This is a floor, not a cap.");
+        }
+        parts.push(decision.reason);
+        if (kind === "ceiling") {
+            parts.push("Confirming runs this one call only. It does not approve a session budget.");
+        }
+        else {
+            parts.push(`Confirming approves a ${usd(budgetUsd ?? SESSION_BUDGET_DEFAULT_USD)} session budget for all deeprelay ` +
+                "inference in this session (chat, embeddings, image and video) and runs this call. To choose another " +
+                `amount (${SESSION_BUDGET_MIN_USD}–${SESSION_BUDGET_MAX_USD} dollars), call again with session_budget_usd ` +
+                "instead of the token.");
+        }
+        parts.push("Call again with the same arguments plus confirmation_token only after the user agrees.");
+        return parts.join(" ");
+    };
+    const quoteOf = (kind, decision, budgetUsd) => async (p) => ({
+        summary: summaryFor(kind, decision, budgetUsd),
+        resolvedParams: p,
+        ...(estimate.pricingKnown ? { estimateMicroCents: estimate.microCents } : {}),
+        isFloor: estimate.isFloor,
+    });
+    const executeRequest = async (p, confirmedBy) => {
+        const { quote_kind: _k, session_budget_usd: _b, confirmation_token: _t, ...req } = p;
+        return serialize(await o.execute(req, runFor(confirmedBy)), env);
+    };
+    const branchFor = (decision, budgetUsd) => {
+        if (decision.verdict === "over_ceiling") {
+            return {
+                params: { ...request, quote_kind: "ceiling" },
+                quoteFn: quoteOf("ceiling", decision),
+                executeFn: (p, t) => executeRequest(p, t),
+                question: o.question,
+            };
+        }
+        return {
+            params: { ...request, quote_kind: "budget", session_budget_usd: budgetUsd },
+            quoteFn: quoteOf("budget", decision, budgetUsd),
+            executeFn: async (p, t) => {
+                (0, budget_js_1.approveBudget)(Math.round(Number(p.session_budget_usd) * 100));
+                // Approval is never a way past the ceiling or the headroom: re-check.
+                const recheck = (0, budget_js_1.checkCall)(checked);
+                if (recheck.verdict !== "ok") {
+                    return quoteOnly(recheck);
+                }
+                return executeRequest(p, t);
+            },
+            question: `Approve a ${usd(budgetUsd)} session budget for deeprelay inference and run this call at the price shown?`,
+        };
+    };
+    // A fresh quote with no elicitation, for a call that still is not runnable
+    // after a budget approval. Redeeming it is a new tool call, which re-enters
+    // runWithBudget from the top.
+    const quoteOnly = async (decision) => {
+        const branch = branchFor(decision, SESSION_BUDGET_DEFAULT_USD);
+        const q = await (0, handshake_js_1.withSpendGuardrail)(o.toolName, branch.params, branch.quoteFn, async () => {
+            throw new Error("unreachable: no token was presented");
+        });
+        if (!(0, result_js_1.isQuoteResult)(q)) {
+            throw new Error("unreachable: a token-less handshake call always quotes");
+        }
+        const extra = { quote_kind: branch.params.quote_kind, session_budget_usd: branch.params.session_budget_usd };
+        return (0, result_js_1.quoteResult)(q, env, extra);
+    };
+    const decision = (0, budget_js_1.checkCall)(checked);
+    if (decision.verdict === "ok") {
+        // Nothing to confirm. A stale token presented here must not stay redeemable.
+        if (typeof token === "string" && token !== "") {
+            (0, handshake_js_1.revokeConfirmation)(token);
+        }
+        const extra = requestedBudgetUsd !== undefined
+            ? {
+                note: "session_budget_usd applies only when a quote asks for a session budget; the current budget is unchanged.",
+            }
+            : undefined;
+        const run = runFor();
+        return serialize(await o.execute(request, run), env, extra);
+    }
+    const budgetUsd = typeof requestedBudgetUsd === "number" ? requestedBudgetUsd : SESSION_BUDGET_DEFAULT_USD;
+    const branch = branchFor(decision, budgetUsd);
+    return confirmThenExecute(o.toolName, { ...branch.params, confirmation_token: token }, branch.quoteFn, branch.executeFn, branch.question, o.ctx);
+}
+const SPEND_ANNOTATIONS = Object.freeze({
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+});
+/** Wrap a billable inference call in the spend tier's quote → budget → confirm dispatch. */
+function defineSpendTool(spec) {
+    const inputSchema = { ...spec.inputSchema, ...exports.SPEND_CONFIRMATION_SHAPE };
+    const schema = zod_1.z.strictObject(inputSchema);
+    const expected = CATALOG_MODALITY[spec.modality];
+    return {
+        name: spec.name,
+        tier: "spend",
+        title: spec.title,
+        description: `${spec.description.trim()} ${exports.SPEND_TIER_SENTENCE}`,
+        inputSchema,
+        annotations: { ...SPEND_ANNOTATIONS },
+        enabledAtBoot: true,
+        async handler(args, ctx) {
+            const env = ctx?.env ?? process.env;
+            let parsed;
+            let config;
+            try {
+                parsed = schema.parse(args ?? {});
+                config = (0, auth_js_1.buildConfiguration)(env);
+            }
+            catch (err) {
+                return (0, result_js_1.fail)((0, errors_js_1.mapSdkError)(err, spec.context, { env }), env);
+            }
+            try {
+                const modelId = String(parsed.model);
+                const rates = await (0, pricing_js_1.ratesFor)(config, modelId);
+                if (rates.modality !== undefined && rates.modality !== expected.catalog) {
+                    const other = toolForCatalogModality(rates.modality);
+                    throw new errors_js_1.QuoteUnavailableError(`Model "${modelId}" is a ${rates.modality} model, not a ${expected.catalog} model.` +
+                        (other !== undefined ? ` Use ${other} for it.` : ""));
+                }
+                const typed = parsed;
+                return await runWithBudget({
+                    toolName: spec.name,
+                    modality: spec.modality,
+                    parsed,
+                    ctx,
+                    config,
+                    rates,
+                    question: spec.question,
+                    describe: spec.describe(typed),
+                    quoteNote: spec.quoteNote,
+                    execute: (req, run) => spec.execute(req, run),
+                });
+            }
+            catch (err) {
+                return (0, result_js_1.fail)(await (0, errors_js_1.mapSdkErrorAsync)(err, spec.context, env), env);
+            }
+        },
+    };
+}
+//# sourceMappingURL=define.js.map

package/dist/tools/spend/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/tools/spend/define.ts"],"names":[],"mappings":"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"}

package/dist/tools/spend/index.d.ts

@@ -0,0 +1,11 @@
+import type { ToolDefinition } from "../types.js";
+import { mediaSpendTools } from "./media.js";
+export { confirmThenExecute, defineSpendTool, runWithBudget, SPEND_CONFIRMATION_SHAPE, SPEND_TIER_SENTENCE, } from "./define.js";
+export type { QuoteKind, SpendExecuted, SpendOutcome, SpendRun, SpendToolSpec } from "./define.js";
+/** Upper bound on max_tokens for one chat call. */
+export declare const CHAT_MAX_TOKENS_LIMIT = 8192;
+/** Upper bound on the number of inputs in one embeddings call (keeps the response bounded). */
+export declare const EMBEDDINGS_MAX_INPUTS = 64;
+/** The spend tier, in SPEND_TOOLS order. */
+export declare const spendTools: ToolDefinition[];
+export { mediaSpendTools };

package/dist/tools/spend/index.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mediaSpendTools = exports.spendTools = exports.EMBEDDINGS_MAX_INPUTS = exports.CHAT_MAX_TOKENS_LIMIT = exports.SPEND_TIER_SENTENCE = exports.SPEND_CONFIRMATION_SHAPE = exports.runWithBudget = exports.defineSpendTool = exports.confirmThenExecute = void 0;
+// The spend tier: billable inference (Phase 104, D-02/D-06/D-07/D-08/D-10).
+//
+// Four tools, one session budget. Chat and embeddings are defined here; image
+// generation and video create live in media.ts. Every one is built by
+// defineSpendTool (define.ts), so pricing, the ceiling → approval → wall →
+// headroom order and the confirmation handshake belong to the tier.
+//
+// Chat and embeddings settle synchronously: reserve the estimate, make the
+// call, reconcile at the actual cost from the response's usage, or release the
+// reservation if the call throws. They send no Idempotency-Key: the API does
+// not accept one on these routes (RESEARCH Pitfall 3).
+//
+// The chat schema deliberately has no `tools` / `response_format`: the API
+// passthrough for them has not landed (CONTEXT, Claude's Discretion), and
+// `stream` is not an argument: the tool always sends stream: false, because an
+// MCP tool result is one message.
+const sdk_1 = require("@deeprelay/sdk");
+const zod_1 = require("zod");
+const budget_js_1 = require("../../guardrail/budget.js");
+const estimate_js_1 = require("../../guardrail/estimate.js");
+const define_js_1 = require("./define.js");
+const media_js_1 = require("./media.js");
+Object.defineProperty(exports, "mediaSpendTools", { enumerable: true, get: function () { return media_js_1.mediaSpendTools; } });
+var define_js_2 = require("./define.js");
+Object.defineProperty(exports, "confirmThenExecute", { enumerable: true, get: function () { return define_js_2.confirmThenExecute; } });
+Object.defineProperty(exports, "defineSpendTool", { enumerable: true, get: function () { return define_js_2.defineSpendTool; } });
+Object.defineProperty(exports, "runWithBudget", { enumerable: true, get: function () { return define_js_2.runWithBudget; } });
+Object.defineProperty(exports, "SPEND_CONFIRMATION_SHAPE", { enumerable: true, get: function () { return define_js_2.SPEND_CONFIRMATION_SHAPE; } });
+Object.defineProperty(exports, "SPEND_TIER_SENTENCE", { enumerable: true, get: function () { return define_js_2.SPEND_TIER_SENTENCE; } });
+/** Upper bound on max_tokens for one chat call. */
+exports.CHAT_MAX_TOKENS_LIMIT = 8192;
+const chatCompletion = (0, define_js_1.defineSpendTool)({
+    name: "deeprelay_chat_completion",
+    title: "Chat completion",
+    description: "Run one chat completion on a deeprelay chat model and return the assistant's reply, token usage and cost. " +
+        "Priced per token from the model's catalog rates: the quote bounds the cost by max_tokens (default " +
+        `${estimate_js_1.DEFAULT_MAX_TOKENS}), and the session budget settles at the actual usage. Use deeprelay_models_list ` +
+        "(modality chat) to find a model id. Returns one complete message; streaming is not offered.",
+    inputSchema: {
+        model: zod_1.z.string().min(1).describe("A chat model id from deeprelay_models_list."),
+        messages: zod_1.z
+            .array(zod_1.z.strictObject({
+            role: zod_1.z.enum(["system", "user", "assistant"]),
+            content: zod_1.z.string(),
+        }))
+            .min(1)
+            .describe("The conversation so far, oldest first."),
+        max_tokens: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(exports.CHAT_MAX_TOKENS_LIMIT)
+            .default(estimate_js_1.DEFAULT_MAX_TOKENS)
+            .describe(`Upper bound on generated tokens (1–${exports.CHAT_MAX_TOKENS_LIMIT}, default ${estimate_js_1.DEFAULT_MAX_TOKENS}). It also bounds the quote.`),
+        temperature: zod_1.z.number().min(0).max(2).optional().describe("Sampling temperature, 0–2."),
+    },
+    modality: "chat",
+    question: "Run this chat completion at the price shown?",
+    context: "running a chat completion",
+    describe: (a) => `Chat completion on ${a.model}: ${a.messages.length} message(s), up to ${a.max_tokens} output tokens`,
+    async execute(a, run) {
+        (0, budget_js_1.recordEstimate)(run.callId, run.estimate.microCents);
+        let res;
+        let actual;
+        try {
+            res = await new sdk_1.InferenceApi(run.config).createChatCompletion({
+                chatCompletionRequest: {
+                    model: a.model,
+                    messages: a.messages,
+                    temperature: a.temperature,
+                    maxTokens: a.max_tokens,
+                    stream: false,
+                },
+            });
+            actual = (0, estimate_js_1.actualMicroCents)("chat", res.usage, run.rates, run.estimate.microCents);
+            (0, budget_js_1.reconcileActual)(run.callId, actual);
+        }
+        catch (err) {
+            (0, budget_js_1.releaseEstimate)(run.callId);
+            throw err;
+        }
+        const choice = res.choices?.[0];
+        return {
+            lead: `Chat completion finished (${choice?.finishReason ?? "no finish reason reported"}).`,
+            payload: {
+                model: res.model,
+                finish_reason: choice?.finishReason ?? null,
+                message: choice?.message ?? null,
+                usage: {
+                    prompt_tokens: res.usage?.promptTokens,
+                    completion_tokens: res.usage?.completionTokens,
+                    total_tokens: res.usage?.totalTokens,
+                },
+                cost: { estimated_micro_cents: run.estimate.microCents, actual_micro_cents: actual },
+                session_budget: (0, budget_js_1.budgetStatus)(),
+            },
+        };
+    },
+});
+/** Upper bound on the number of inputs in one embeddings call (keeps the response bounded). */
+exports.EMBEDDINGS_MAX_INPUTS = 64;
+const embeddingsCreate = (0, define_js_1.defineSpendTool)({
+    name: "deeprelay_embeddings_create",
+    title: "Create embeddings",
+    description: "Embed one string or a list of up to 64 strings with a deeprelay embedding model and return the vectors, " +
+        "token usage and cost. Priced per input token from the model's catalog rate; the session budget settles at " +
+        "the actual prompt tokens. Use deeprelay_models_list (modality embedding) to find a model id.",
+    inputSchema: {
+        model: zod_1.z.string().min(1).describe("An embedding model id from deeprelay_models_list."),
+        input: zod_1.z
+            .union([
+            zod_1.z.string().min(1),
+            zod_1.z.array(zod_1.z.string().min(1)).min(1).max(exports.EMBEDDINGS_MAX_INPUTS),
+        ])
+            .describe(`One non-empty string, or 1–${exports.EMBEDDINGS_MAX_INPUTS} non-empty strings.`),
+        dimensions: zod_1.z.number().int().positive().optional().describe("Output dimensions, for models that support it."),
+        encoding_format: zod_1.z.enum(["float"]).optional().describe("Only float is offered."),
+    },
+    modality: "embeddings",
+    question: "Create these embeddings at the price shown?",
+    context: "creating embeddings",
+    describe: (a) => `Embeddings on ${a.model}: ${typeof a.input === "string" ? 1 : a.input.length} input(s)`,
+    async execute(a, run) {
+        (0, budget_js_1.recordEstimate)(run.callId, run.estimate.microCents);
+        let res;
+        let actual;
+        try {
+            res = await new sdk_1.InferenceApi(run.config).createEmbeddings({
+                embeddingsRequest: {
+                    model: a.model,
+                    input: a.input,
+                    dimensions: a.dimensions,
+                    encodingFormat: a.encoding_format,
+                },
+            });
+            actual = (0, estimate_js_1.actualMicroCents)("embeddings", res.usage, run.rates, run.estimate.microCents);
+            (0, budget_js_1.reconcileActual)(run.callId, actual);
+        }
+        catch (err) {
+            (0, budget_js_1.releaseEstimate)(run.callId);
+            throw err;
+        }
+        const data = res.data ?? [];
+        return {
+            lead: `Created ${data.length} embedding(s).`,
+            payload: {
+                model: res.model,
+                count: data.length,
+                dimensions: data[0]?.embedding.length,
+                embeddings: data.map((e) => e.embedding),
+                usage: { prompt_tokens: res.usage?.promptTokens, total_tokens: res.usage?.totalTokens },
+                cost: { estimated_micro_cents: run.estimate.microCents, actual_micro_cents: actual },
+                session_budget: (0, budget_js_1.budgetStatus)(),
+            },
+        };
+    },
+});
+/** The spend tier, in SPEND_TOOLS order. */
+exports.spendTools = [chatCompletion, embeddingsCreate, ...media_js_1.mediaSpendTools];
+//# sourceMappingURL=index.js.map

package/dist/tools/spend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/spend/index.ts"],"names":[],"mappings":";;;AAAA,4EAA4E;AAC5E,EAAE;AACF,8EAA8E;AAC9E,sEAAsE;AACtE,2EAA2E;AAC3E,oEAAoE;AACpE,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAC/E,6EAA6E;AAC7E,uDAAuD;AACvD,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,+EAA+E;AAC/E,kCAAkC;AAClC,wCAA8C;AAC9C,6BAAwB;AAExB,yDAA2G;AAC3G,6DAAmF;AAEnF,2CAA8C;AAC9C,yCAA6C;AAsJpC,gGAtJA,0BAAe,OAsJA;AApJxB,yCAMqB;AALnB,+GAAA,kBAAkB,OAAA;AAClB,4GAAA,eAAe,OAAA;AACf,0GAAA,aAAa,OAAA;AACb,qHAAA,wBAAwB,OAAA;AACxB,gHAAA,mBAAmB,OAAA;AAIrB,mDAAmD;AACtC,QAAA,qBAAqB,GAAG,IAAI,CAAC;AAE1C,MAAM,cAAc,GAAG,IAAA,2BAAe,EAAC;IACrC,IAAI,EAAE,2BAA2B;IACjC,KAAK,EAAE,iBAAiB;IACxB,WAAW,EACT,4GAA4G;QAC5G,oGAAoG;QACpG,GAAG,gCAAkB,mFAAmF;QACxG,6FAA6F;IAC/F,WAAW,EAAE;QACX,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6CAA6C,CAAC;QAChF,QAAQ,EAAE,OAAC;aACR,KAAK,CACJ,OAAC,CAAC,YAAY,CAAC;YACb,IAAI,EAAE,OAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;YAC7C,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE;SACpB,CAAC,CACH;aACA,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,wCAAwC,CAAC;QACrD,UAAU,EAAE,OAAC;aACV,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,6BAAqB,CAAC;aAC1B,OAAO,CAAC,gCAAkB,CAAC;aAC3B,QAAQ,CAAC,sCAAsC,6BAAqB,aAAa,gCAAkB,8BAA8B,CAAC;QACrI,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;KACxF;IACD,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,8CAA8C;IACxD,OAAO,EAAE,2BAA2B;IACpC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CACd,sBAAsB,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,sBAAsB,CAAC,CAAC,UAAU,gBAAgB;IACvG,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG;QAClB,IAAA,0BAAc,EAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACpD,IAAI,GAAG,CAAC;QACR,IAAI,MAAc,CAAC;QACnB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,kBAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,oBAAoB,CAAC;gBAC5D,qBAAqB,EAAE;oBACrB,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,QAAQ,EAAE,CAAC,CAAC,QAAQ;oBACpB,WAAW,EAAE,CAAC,CAAC,WAAW;oBAC1B,SAAS,EAAE,CAAC,CAAC,UAAU;oBACvB,MAAM,EAAE,KAAK;iBACd;aACF,CAAC,CAAC;YACH,MAAM,GAAG,IAAA,8BAAgB,EAAC,MAAM,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YACjF,IAAA,2BAAe,EAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAA,2BAAe,EAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC5B,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,6BAA6B,MAAM,EAAE,YAAY,IAAI,2BAA2B,IAAI;YAC1F,OAAO,EAAE;gBACP,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,aAAa,EAAE,MAAM,EAAE,YAAY,IAAI,IAAI;gBAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,IAAI;gBAChC,KAAK,EAAE;oBACL,aAAa,EAAE,GAAG,CAAC,KAAK,EAAE,YAAY;oBACtC,iBAAiB,EAAE,GAAG,CAAC,KAAK,EAAE,gBAAgB;oBAC9C,YAAY,EAAE,GAAG,CAAC,KAAK,EAAE,WAAW;iBACrC;gBACD,IAAI,EAAE,EAAE,qBAAqB,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE;gBACpF,cAAc,EAAE,IAAA,wBAAY,GAAE;aAC/B;SACF,CAAC;IACJ,CAAC;CACF,CAAC,CAAC;AAEH,+FAA+F;AAClF,QAAA,qBAAqB,GAAG,EAAE,CAAC;AAExC,MAAM,gBAAgB,GAAG,IAAA,2BAAe,EAAC;IACvC,IAAI,EAAE,6BAA6B;IACnC,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,0GAA0G;QAC1G,4GAA4G;QAC5G,8FAA8F;IAChG,WAAW,EAAE;QACX,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,mDAAmD,CAAC;QACtF,KAAK,EAAE,OAAC;aACL,KAAK,CAAC;YACL,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACjB,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,6BAAqB,CAAC;SAC7D,CAAC;aACD,QAAQ,CAAC,8BAA8B,6BAAqB,qBAAqB,CAAC;QACrF,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;QAC7G,eAAe,EAAE,OAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;KACjF;IACD,QAAQ,EAAE,YAAY;IACtB,QAAQ,EAAE,6CAA6C;IACvD,OAAO,EAAE,qBAAqB;IAC9B,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CACd,iBAAiB,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,WAAW;IAC1F,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG;QAClB,IAAA,0BAAc,EAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACpD,IAAI,GAAG,CAAC;QACR,IAAI,MAAc,CAAC;QACnB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,kBAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,gBAAgB,CAAC;gBACxD,iBAAiB,EAAE;oBACjB,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,UAAU,EAAE,CAAC,CAAC,UAAU;oBACxB,cAAc,EAAE,CAAC,CAAC,eAAe;iBAClC;aACF,CAAC,CAAC;YACH,MAAM,GAAG,IAAA,8BAAgB,EAAC,YAAY,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YACvF,IAAA,2BAAe,EAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAA,2BAAe,EAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC5B,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;QAC5B,OAAO;YACL,IAAI,EAAE,WAAW,IAAI,CAAC,MAAM,gBAAgB;YAC5C,OAAO,EAAE;gBACP,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,KAAK,EAAE,IAAI,CAAC,MAAM;gBAClB,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM;gBACrC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBACxC,KAAK,EAAE,EAAE,aAAa,EAAE,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE;gBACvF,IAAI,EAAE,EAAE,qBAAqB,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE;gBACpF,cAAc,EAAE,IAAA,wBAAY,GAAE;aAC/B;SACF,CAAC;IACJ,CAAC;CACF,CAAC,CAAC;AAEH,4CAA4C;AAC/B,QAAA,UAAU,GAAqB,CAAC,cAAc,EAAE,gBAAgB,EAAE,GAAG,0BAAe,CAAC,CAAC"}

package/dist/tools/spend/media.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition } from "../types.js";
+export declare const IMAGE_MAX_COUNT = 4;
+export declare const VIDEO_MAX_SECONDS = 30;
+/** The floor wording every video quote carries (D-07). */
+export declare const VIDEO_FLOOR_NOTE = "This is a floor, not a cap \u2014 the final charge is known when the job completes.";
+/** The image's MIME type from its base64 signature; PNG when unrecognized. */
+export declare function imageMimeType(b64: string): string;
+/** Image then video, in SPEND_TOOLS order. */
+export declare const mediaSpendTools: ToolDefinition[];