@deeprelay/mcp 0.0.1 → 0.1.1

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":"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"}

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[];

package/dist/tools/spend/media.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mediaSpendTools = exports.VIDEO_FLOOR_NOTE = exports.VIDEO_MAX_SECONDS = exports.IMAGE_MAX_COUNT = void 0;
+exports.imageMimeType = imageMimeType;
+// Image generation and video create: the media half of the spend tier
+// (Phase 104, D-02/D-06/D-07). Both go through defineSpendTool, so they share
+// the one session budget, the per-call ceiling and the confirmation handshake
+// with chat and embeddings.
+//
+// Image is synchronous: reserve, generate, settle at the actual image count.
+// Its result is native MCP image content (one block per image) followed by one
+// text block with usage and cost. ok() only builds text, so the execute step
+// returns a prebuilt ToolResult, which the dispatch passes through unchanged;
+// the text block is still built by ok() (sanitized and redacted).
+//
+// Video is asynchronous (RESEARCH Pitfall 2). The create call returns a queued
+// job with no cost, so this handler reserves the catalog from-price (a FLOOR)
+// under the returned job id and does not settle anything itself. The video
+// reads (readonly/video-reads.ts) settle the reservation when they observe the
+// job finished: at cost_cents on completion, released on failed, cancelled or
+// expired.
+//
+// Both media calls send an Idempotency-Key header (RESEARCH Pitfall 3): the
+// confirmation token when the call was confirmed, else the per-call id, so a
+// transport retry cannot charge twice (T-104-29).
+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 result_js_1 = require("../result.js");
+const define_js_1 = require("./define.js");
+/** "WxH", e.g. 1024x1024. */
+const SIZE_PATTERN = /^\d{2,4}x\d{2,4}$/;
+exports.IMAGE_MAX_COUNT = 4;
+exports.VIDEO_MAX_SECONDS = 30;
+/** The floor wording every video quote carries (D-07). */
+exports.VIDEO_FLOOR_NOTE = "This is a floor, not a cap — the final charge is known when the job completes.";
+/** The image's MIME type from its base64 signature; PNG when unrecognized. */
+function imageMimeType(b64) {
+    if (b64.startsWith("/9j/"))
+        return "image/jpeg";
+    if (b64.startsWith("UklGR"))
+        return "image/webp";
+    if (b64.startsWith("R0lGOD"))
+        return "image/gif";
+    return "image/png";
+}
+const imagesGenerate = (0, define_js_1.defineSpendTool)({
+    name: "deeprelay_images_generate",
+    title: "Generate images",
+    description: "Generate 1–4 images from a text prompt with a deeprelay image model and return them as image content, " +
+        "with usage and cost. Priced per image, or per megapixel of the requested size, from the model's catalog " +
+        "rate; the session budget settles at the number of images actually returned. Use deeprelay_models_list " +
+        "(modality image) to find a model id.",
+    inputSchema: {
+        model: zod_1.z.string().min(1).describe("An image model id from deeprelay_models_list."),
+        prompt: zod_1.z.string().min(1).max(4000).describe("What to draw (up to 4000 characters)."),
+        n: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(exports.IMAGE_MAX_COUNT)
+            .default(1)
+            .describe(`How many images (1–${exports.IMAGE_MAX_COUNT}, default 1). Each one is billed.`),
+        size: zod_1.z
+            .string()
+            .regex(SIZE_PATTERN)
+            .optional()
+            .describe("Output size as WIDTHxHEIGHT, e.g. 1024x1024. Per-megapixel models price by it."),
+    },
+    modality: "image",
+    question: "Generate these images at the price shown?",
+    context: "generating images",
+    describe: (a) => `Generate ${a.n} image(s) on ${a.model}${a.size !== undefined ? ` at ${a.size}` : ""}`,
+    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).createImage({
+                imagesGenerationsRequest: { model: a.model, prompt: a.prompt, n: a.n, size: a.size, responseFormat: "b64_json" },
+                idempotencyKey: run.idempotencyKey,
+            });
+            actual = (0, estimate_js_1.actualMicroCents)("image", res.usage, run.rates, run.estimate.microCents, { size: a.size });
+            (0, budget_js_1.reconcileActual)(run.callId, actual);
+        }
+        catch (err) {
+            (0, budget_js_1.releaseEstimate)(run.callId);
+            throw err;
+        }
+        const images = (res.data ?? [])
+            .filter((d) => typeof d.b64Json === "string" && d.b64Json !== "")
+            .map((d) => ({ type: "image", data: d.b64Json, mimeType: imageMimeType(d.b64Json) }));
+        const summary = (0, result_js_1.ok)({
+            lead: `Generated ${images.length} image(s).`,
+            model: a.model,
+            count: images.length,
+            usage: { image_count: res.usage?.imageCount },
+            cost: { estimated_micro_cents: run.estimate.microCents, actual_micro_cents: actual },
+            session_budget: (0, budget_js_1.budgetStatus)(),
+        }, { env: run.env });
+        return { content: [...images, ...summary.content] };
+    },
+});
+// Keep this definition last in the file: a test scans from here to the end
+// and asserts the video path contains no settlement call.
+const videosCreate = (0, define_js_1.defineSpendTool)({
+    name: "deeprelay_videos_create",
+    title: "Create a video",
+    description: "Start an asynchronous text-to-video job on a deeprelay video model. Priced from the catalog's per-clip " +
+        "from-price, or per second of the requested length; the quote is a floor, not a cap, and the real charge " +
+        "is known only when the job completes. The floor is held against the session budget until " +
+        "deeprelay_videos_get or deeprelay_videos_list sees the job finish, which settles it at the actual cost " +
+        "(or releases it if the job failed or was cancelled). Download a finished clip with deeprelay_videos_content.",
+    inputSchema: {
+        model: zod_1.z.string().min(1).describe("A video model id from deeprelay_models_list."),
+        prompt: zod_1.z.string().min(1).max(4000).describe("What the clip should show (up to 4000 characters)."),
+        seconds: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(exports.VIDEO_MAX_SECONDS)
+            .optional()
+            .describe(`Clip length in seconds (1–${exports.VIDEO_MAX_SECONDS}). Per-second models price by it.`),
+        size: zod_1.z.string().regex(SIZE_PATTERN).optional().describe("Output size as WIDTHxHEIGHT, e.g. 1280x720."),
+    },
+    modality: "video",
+    question: "Start this video job at the floor price shown?",
+    context: "creating a video job",
+    quoteNote: exports.VIDEO_FLOOR_NOTE,
+    describe: (a) => `Start a video job on ${a.model}${a.seconds !== undefined ? ` for ${a.seconds}s` : ""}${a.size !== undefined ? ` at ${a.size}` : ""}`,
+    async execute(a, run) {
+        // Hold the floor while the create call is in flight, so a parallel call
+        // cannot spend the same headroom.
+        (0, budget_js_1.recordEstimate)(run.callId, run.estimate.microCents);
+        let job;
+        try {
+            job = await new sdk_1.InferenceApi(run.config).createVideo({
+                videoCreateRequest: { model: a.model, prompt: a.prompt, seconds: a.seconds, size: a.size },
+                idempotencyKey: run.idempotencyKey,
+            });
+        }
+        catch (err) {
+            (0, budget_js_1.releaseEstimate)(run.callId);
+            throw err;
+        }
+        // Keyed by the real job id; a video read settles it.
+        (0, budget_js_1.registerPendingVideo)(job.id, run.callId, run.estimate.microCents);
+        return {
+            lead: `Video job ${job.id} queued. Call deeprelay_videos_get to poll; the session budget settles when it completes.`,
+            payload: {
+                video_id: job.id,
+                status: job.status,
+                model: job.model ?? a.model,
+                seconds: job.seconds ?? a.seconds ?? null,
+                floor_micro_cents: run.estimate.microCents,
+                session_budget: (0, budget_js_1.budgetStatus)(),
+            },
+        };
+    },
+});
+/** Image then video, in SPEND_TOOLS order. */
+exports.mediaSpendTools = [imagesGenerate, videosCreate];
+//# sourceMappingURL=media.js.map

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

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

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

@@ -0,0 +1,17 @@
+import { type Configuration, type ModelModalityEnum } from "@deeprelay/sdk";
+import type { PricingLike } from "../../guardrail/estimate.js";
+/** How long one model's rates are reused before the catalog is read again. */
+export declare const RATE_CACHE_TTL_MS: number;
+/** A model's rates plus the two catalog facts the spend tier checks against. */
+export interface ModelRates extends PricingLike {
+    modelId: string;
+    /** The catalog modality (chat | embedding | image | video), when published. */
+    modality?: ModelModalityEnum;
+}
+/** Test-only: forget every cached rate. */
+export declare function resetPricingCacheForTests(): void;
+/**
+ * The model's current rates. The cache is keyed by base URL as well as model
+ * id, so a demo override and production never share an entry.
+ */
+export declare function ratesFor(config: Configuration, modelId: string, now?: () => number): Promise<ModelRates>;

package/dist/tools/spend/pricing.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RATE_CACHE_TTL_MS = void 0;
+exports.resetPricingCacheForTests = resetPricingCacheForTests;
+exports.ratesFor = ratesFor;
+// Catalog rates for the spend tier (Phase 104, D-06). Authored fresh (D-12).
+//
+// Every spend quote prices the call from the model's own catalog entry
+// (InferenceApi.getModel), never from a hard-coded table, so a price change on
+// the platform reaches the next quote without a release. The result is cached
+// per process for RATE_CACHE_TTL_MS: a quote followed by its confirming call a
+// few seconds later should not fetch the catalog twice, and a stale rate lasts
+// at most ten minutes.
+//
+// An unknown model is not handled here: the SDK's 404 propagates to the tool's
+// error funnel (errors.ts), which names it as "not found" without a quote and
+// without minting a token.
+const sdk_1 = require("@deeprelay/sdk");
+const budget_js_1 = require("../../guardrail/budget.js");
+/** How long one model's rates are reused before the catalog is read again. */
+exports.RATE_CACHE_TTL_MS = 10 * 60 * 1000;
+const cache = new Map();
+/** Test-only: forget every cached rate. */
+function resetPricingCacheForTests() {
+    cache.clear();
+}
+function pick(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * The model's current rates. The cache is keyed by base URL as well as model
+ * id, so a demo override and production never share an entry.
+ */
+async function ratesFor(config, modelId, now = Date.now) {
+    const key = `${config.basePath}\u0000${modelId}`;
+    const hit = cache.get(key);
+    if (hit !== undefined && hit.expiresAt > now()) {
+        return hit.rates;
+    }
+    const model = await new sdk_1.InferenceApi(config).getModel({ id: modelId });
+    const p = model.pricing ?? {};
+    const rates = {
+        modelId: model.id ?? modelId,
+        modality: model.modality,
+        inputPer1mTokensCents: pick(p.inputPer1mTokensCents),
+        outputPer1mTokensCents: pick(p.outputPer1mTokensCents),
+        cachedInputPer1mTokensMicrocents: pick(p.cachedInputPer1mTokensMicrocents),
+        perImageCents: pick(p.perImageCents),
+        perImageMicrocents: pick(p.perImageMicrocents),
+        perMpxlMicrocents: pick(p.perMpxlMicrocents),
+        perVideoMicrocents: pick(p.perVideoMicrocents),
+        perVideoSecondMicrocents: pick(p.perVideoSecondMicrocents) ??
+            (pick(p.perVideoSecondCents) === undefined ? undefined : p.perVideoSecondCents * budget_js_1.MICRO_CENTS_PER_CENT),
+    };
+    cache.set(key, { rates, expiresAt: now() + exports.RATE_CACHE_TTL_MS });
+    return rates;
+}
+//# sourceMappingURL=pricing.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../../src/tools/spend/pricing.ts"],"names":[],"mappings":";;;AAmCA,8DAEC;AAUD,4BA6BC;AA5ED,6EAA6E;AAC7E,EAAE;AACF,uEAAuE;AACvE,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,uBAAuB;AACvB,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,2BAA2B;AAC3B,wCAA0F;AAE1F,yDAAiE;AAGjE,8EAA8E;AACjE,QAAA,iBAAiB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAchD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C,2CAA2C;AAC3C,SAAgB,yBAAyB;IACvC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED,SAAS,IAAI,CAAC,KAAyB;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjF,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,QAAQ,CAC5B,MAAqB,EACrB,OAAe,EACf,MAAoB,IAAI,CAAC,GAAG;IAE5B,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,QAAQ,SAAS,OAAO,EAAE,CAAC;IACjD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,SAAS,GAAG,GAAG,EAAE,EAAE,CAAC;QAC/C,OAAO,GAAG,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,IAAI,kBAAY,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACvE,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAe;QACxB,OAAO,EAAE,KAAK,CAAC,EAAE,IAAI,OAAO;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,qBAAqB,EAAE,IAAI,CAAC,CAAC,CAAC,qBAAqB,CAAC;QACpD,sBAAsB,EAAE,IAAI,CAAC,CAAC,CAAC,sBAAsB,CAAC;QACtD,gCAAgC,EAAE,IAAI,CAAC,CAAC,CAAC,gCAAgC,CAAC;QAC1E,aAAa,EAAE,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC;QACpC,kBAAkB,EAAE,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC;QAC9C,iBAAiB,EAAE,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC;QAC5C,kBAAkB,EAAE,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC;QAC9C,wBAAwB,EACtB,IAAI,CAAC,CAAC,CAAC,wBAAwB,CAAC;YAChC,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,CAAC,CAAC,mBAA8B,GAAG,gCAAoB,CAAC;KACrH,CAAC;IACF,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,yBAAiB,EAAE,CAAC,CAAC;IAChE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/tools/types.d.ts

@@ -0,0 +1,45 @@
+import type { ZodRawShape } from "zod";
+import type { ElicitationHost } from "../guardrail/types.js";
+import type { ToolName } from "../roster.js";
+/** Process environment view (the DEEPRELAY_API_KEY / base-URL override source). */
+export type Env = Record<string, string | undefined>;
+export type ToolTier = "read" | "write" | "spend";
+export type ToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/** Compatible with MCP's CallToolResult. */
+export interface ToolResult {
+    content: ToolContent[];
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/** Per-call context the registration door threads into a handler. */
+export interface ToolContext {
+    env?: Env;
+    /** Present only when the server can reach the client's elicitation surface. */
+    elicitation?: ElicitationHost;
+}
+/** MCP ToolAnnotations. All four hints are always set explicitly. */
+export interface ToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+export interface ToolDefinition {
+    name: ToolName;
+    tier: ToolTier;
+    title: string;
+    /** Hand-authored and written for the agent (Phase 80 D-14 reasoning). */
+    description: string;
+    inputSchema: ZodRawShape;
+    annotations: ToolAnnotations;
+    /** See the file header. False for deeprelay_deposits_create_crypto only. */
+    enabledAtBoot: boolean;
+    handler(args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>;
+}

package/dist/tools/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,60 @@
+import type { Configuration } from "@deeprelay/sdk";
+import { z, type ZodRawShape } from "zod";
+import type { Quote } from "../../guardrail/types.js";
+import type { WriteToolName } from "../../roster.js";
+import type { Env, ToolDefinition } from "../types.js";
+/** Appended to every write description. The tier's contract, stated to the agent. */
+export declare const WRITE_TIER_SENTENCE: string;
+/** The one extra argument every write tool accepts. */
+export declare const CONFIRMATION_TOKEN_SHAPE: {
+    confirmation_token: z.ZodOptional<z.ZodString>;
+};
+/** A quote whose resolvedParams are typed for the tool's execute step. */
+export interface WriteQuote<R> extends Omit<Quote, "resolvedParams" | "estimateMicroCents" | "isFloor"> {
+    resolvedParams: R;
+}
+/** What a write's execute step returns. */
+export interface WriteExecuted {
+    /** One sentence the agent can relay as-is. */
+    lead: string;
+    /** Sanitized before it reaches the agent. */
+    payload: unknown;
+    /** One-time reveal, merged AFTER sanitization. Only webhook create sets it. */
+    revealOnce?: Record<string, string>;
+}
+/**
+ * Thrown from a write's quote or execute when the requested change is already
+ * true, e.g. clearing a spending limit on an account that has none. The
+ * factory returns `executed` as an ordinary result, not an error: the agent
+ * should report "nothing to do", not retry or apologise for a failure. Thrown
+ * from quote it mints no token, so nothing is left behind to confirm.
+ */
+export declare class WriteNothingToDo extends Error {
+    readonly executed: WriteExecuted;
+    constructor(executed: WriteExecuted);
+}
+export interface WriteToolSpec<Shape extends ZodRawShape, R extends Record<string, unknown>> {
+    name: WriteToolName;
+    title: string;
+    /** Agent-shaped. The tier sentence is appended automatically. */
+    description: string;
+    inputSchema: Shape;
+    /** True for delete/cancel: the change cannot be undone. */
+    destructive: boolean;
+    /** Only deeprelay_deposits_create_crypto sets this to false (D-03). */
+    enabledAtBoot?: boolean;
+    /** The yes/no question put to the user through elicitation. */
+    question: string | ((args: z.infer<z.ZodObject<Shape>>) => string);
+    /** What was being attempted, for error messages ("creating a webhook endpoint"). */
+    context: string;
+    /**
+     * Describe the change. Throwing (e.g. QuoteUnavailableError) mints no token.
+     * resolvedParams are what execute receives, never the second call's raw args.
+     */
+    quote(args: z.infer<z.ZodObject<Shape>>, config: Configuration, env: Env): Promise<WriteQuote<R>>;
+    execute(resolved: R, config: Configuration, env: Env): Promise<WriteExecuted>;
+    /** Tool-specific wording for an HTTP status; undefined falls back to the shared mapper. */
+    overrideError?(status: number | undefined, err: unknown): string | undefined;
+}
+/** Wrap a mutation in the write tier's confirm-once handshake. */
+export declare function defineWriteTool<Shape extends ZodRawShape, R extends Record<string, unknown>>(spec: WriteToolSpec<Shape, R>): ToolDefinition;