@deeprelay/mcp 0.0.1 → 0.1.0

package/dist/tools/readonly/index.js

@@ -0,0 +1,292 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readonlyTools = exports.videoReadTools = exports.VIDEO_TMP_DIR = exports.observeVideoJob = exports.READ_ANNOTATIONS = exports.defineTool = void 0;
+exports.renderSessionBudget = renderSessionBudget;
+// The free read tier (Phase 104, D-03/D-04/D-05/D-10). Authored fresh (D-12).
+//
+// Every tool here is a single GET mapped to one @deeprelay/sdk method (D-05),
+// built with defineTool (define.ts): no confirmation, no quote, no budget
+// accounting, and every result goes through ok(), so credential fields are
+// sanitized and key-shaped text is redacted before the agent sees it.
+//
+// There is no operations tool (D-04). The video reads, which are the only
+// place a pending video reservation settles (D-07), live in video-reads.ts.
+const sdk_1 = require("@deeprelay/sdk");
+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 define_js_1 = require("./define.js");
+const video_reads_js_1 = require("./video-reads.js");
+var define_js_2 = require("./define.js");
+Object.defineProperty(exports, "defineTool", { enumerable: true, get: function () { return define_js_2.defineTool; } });
+Object.defineProperty(exports, "READ_ANNOTATIONS", { enumerable: true, get: function () { return define_js_2.READ_ANNOTATIONS; } });
+var video_reads_js_2 = require("./video-reads.js");
+Object.defineProperty(exports, "observeVideoJob", { enumerable: true, get: function () { return video_reads_js_2.observeVideoJob; } });
+Object.defineProperty(exports, "VIDEO_TMP_DIR", { enumerable: true, get: function () { return video_reads_js_2.VIDEO_TMP_DIR; } });
+Object.defineProperty(exports, "videoReadTools", { enumerable: true, get: function () { return video_reads_js_2.videoReadTools; } });
+/** Render 1e-6-cent units as dollars, for the agent's summary to the user. */
+function dollars(microCents) {
+    return `$${(microCents / (budget_js_1.MICRO_CENTS_PER_CENT * 100)).toFixed(2)}`;
+}
+/** Run a read whose 404 is a normal answer ("nothing configured"), not an error. */
+async function orNotFound(call, onNotFound) {
+    try {
+        return await call();
+    }
+    catch (err) {
+        if ((0, errors_js_1.httpStatusOf)(err) === 404) {
+            return onNotFound();
+        }
+        throw err;
+    }
+}
+/** The in-process session budget (D-06/D-08), in dollars, with pending video holds. */
+function renderSessionBudget() {
+    const s = (0, budget_js_1.budgetStatus)();
+    return {
+        approved: s.approved,
+        limit: dollars(s.limitCents * budget_js_1.MICRO_CENTS_PER_CENT),
+        per_call_ceiling: dollars(s.ceilingMicroCents),
+        settled: dollars(s.settledMicroCents),
+        reserved: dollars(s.pendingMicroCents),
+        remaining: dollars(s.remainingMicroCents),
+        pending_video_reservations: (0, budget_js_1.pendingVideoReservations)().map((r) => ({
+            video_id: r.videoId,
+            reserved: dollars(r.microCents),
+        })),
+        note: s.approved
+            ? "Spend tools draw from this budget. Pending video reservations settle when deeprelay_videos_get or deeprelay_videos_list observes the job finished."
+            : `No session budget approved yet. The first spend call asks the user to approve one (default ${dollars(s.limitCents * budget_js_1.MICRO_CENTS_PER_CENT)}).`,
+    };
+}
+function balanceView(b) {
+    return {
+        balance_cents: b.balanceCents,
+        balance_dollars: b.balanceDollars,
+        auto_pay_enabled: b.autoPayEnabled,
+    };
+}
+function spendingLimitView(l) {
+    return {
+        monthly_limit_cents: l.monthlyLimitCents,
+        current_month_spend_cents: l.currentMonthSpendCents,
+        percent_used: l.percentUsed,
+        daily_limit_cents: l.dailyLimitCents ?? null,
+        current_day_spend_cents: l.currentDaySpendCents,
+        enforcement: l.enforcement,
+    };
+}
+const FREE = "Free: a read-only call with no charge and no confirmation.";
+/** Diagnostics, catalog and usage reads. */
+const coreReadTools = [
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_auth_status",
+        title: "Check deeprelay credentials and session budget",
+        description: "Call this FIRST in a session. It confirms the configured deeprelay API key works and reports, in one call: " +
+            "the API base in use, the account's monthly/daily spending limit (null when none is configured), the prepaid " +
+            "balance, and this session's spend budget (approved or not, settled and reserved spend, remaining headroom, " +
+            `and any video jobs whose cost is still pending). ${FREE} It never returns the key itself.`,
+        inputSchema: {},
+        context: "checking the deeprelay credentials",
+        async call(_args, config, env) {
+            const billing = new sdk_1.BillingApi(config);
+            const limit = await orNotFound(() => billing.getSpendingLimit(), () => null);
+            const balance = await billing.getBalance();
+            return {
+                authenticated: true,
+                api_base: (0, auth_js_1.resolveBaseUrl)(env),
+                spending_limit: limit === null ? null : spendingLimitView(limit),
+                balance: balanceView(balance),
+                session_budget: renderSessionBudget(),
+            };
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_health",
+        title: "Check deeprelay API liveness",
+        description: "Is the deeprelay API up? Call this when other calls fail with network errors, to tell an outage apart from " +
+            `a configuration problem. Works even when no API key is configured. ${FREE}`,
+        inputSchema: {},
+        context: "checking deeprelay API health",
+        keyless: true,
+        async call(_args, config, env) {
+            const health = await new sdk_1.MetaApi(config).getHealth();
+            return { status: health.status ?? "unknown", api_base: (0, auth_js_1.resolveBaseUrl)(env) };
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_models_list",
+        title: "List deeprelay models",
+        description: "List the models deeprelay serves, with their modality (chat, embedding, image, video) and pricing. Call this " +
+            "before any inference call to pick a model id and see what it costs; filter with `modality`. " +
+            FREE,
+        inputSchema: {
+            modality: zod_1.z.enum(sdk_1.ListModelsModalityEnum).optional().describe("Only models of this modality."),
+        },
+        context: "listing models",
+        async call(args, config) {
+            return new sdk_1.InferenceApi(config).listModels({ modality: args.modality });
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_models_get",
+        title: "Get one deeprelay model",
+        description: "Get one model by id: modality, parameters and pricing. Call this to confirm a model id exists and to read " +
+            `its exact rates before quoting a spend call. ${FREE}`,
+        inputSchema: {
+            id: zod_1.z.string().min(1).describe("Model id, as returned by deeprelay_models_list."),
+        },
+        context: "getting a model",
+        async call(args, config) {
+            return new sdk_1.InferenceApi(config).getModel({ id: args.id });
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_inference_preflight",
+        title: "Preflight an inference call",
+        description: "Will a call to this model succeed for this account right now? Returns a verdict (ok, warn or block) with the " +
+            "reason and whether the account is funded, subscribed and plan-covered for the model. Call this before a spend " +
+            `call when unsure, instead of trying the call and failing. ${FREE}`,
+        inputSchema: {
+            model: zod_1.z.string().min(1).describe("Model id to check."),
+        },
+        context: "preflighting an inference call",
+        async call(args, config) {
+            return new sdk_1.InferenceApi(config).inferencePreflight({ model: args.model });
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_usage_get",
+        title: "Get deeprelay usage",
+        description: "How much has this account used and spent, over time? Returns time-bucketed usage (hour, day, week or month; " +
+            "default day, last 31 buckets). Pass `cursor` from `nextCursor` to page. Use this to answer spend questions " +
+            `about past days; for this session's spend use deeprelay_auth_status. ${FREE}`,
+        inputSchema: {
+            bucket: zod_1.z.enum(sdk_1.ListUsageBucketEnum).default("day").describe("Bucket width."),
+            start: zod_1.z.iso.datetime({ offset: true }).optional().describe("ISO-8601 start of the window."),
+            end: zod_1.z.iso.datetime({ offset: true }).optional().describe("ISO-8601 end of the window."),
+            cursor: zod_1.z.string().min(1).optional().describe("Page cursor from a previous result's nextCursor."),
+            limit: zod_1.z.number().int().min(1).max(100).default(31).describe("Buckets per page (1-100)."),
+        },
+        context: "getting usage",
+        async call(args, config) {
+            return new sdk_1.UsageApi(config).listUsage({
+                bucket: args.bucket,
+                start: args.start === undefined ? undefined : new Date(args.start),
+                end: args.end === undefined ? undefined : new Date(args.end),
+                cursor: args.cursor,
+                limit: args.limit,
+            });
+        },
+    }),
+];
+const DEPOSITS_NOTE = "Crypto deposits are visible only on accounts with crypto deposits enabled. If the feature is not enabled the " +
+    "result is `{ crypto_deposits_enabled: false }`: that is a final answer, not an error, so do not retry.";
+const NO_SECRET_NOTE = "The endpoint's signing secret is never returned by any read; it is shown once, when the endpoint is created.";
+/** Webhook endpoints without their signing secret, even if the API sent one. */
+function withoutSecret(endpoint) {
+    const { secret: _secret, ...rest } = endpoint;
+    return rest;
+}
+/** Billing and webhook reads. */
+const billingReadTools = [
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_balance_get",
+        title: "Get deeprelay balance",
+        description: "How much prepaid credit does the account have? Returns the balance in cents and dollars and the auto-pay " +
+            `settings. Call this before a large spend, or after a 402 insufficient-balance error. ${FREE}`,
+        inputSchema: {},
+        context: "getting the balance",
+        async call(_args, config) {
+            return new sdk_1.BillingApi(config).getBalance();
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_spending_limit_get",
+        title: "Get the deeprelay spending limit",
+        description: "What is the account's monthly (and optional daily) spending limit, and how much of it is used? When no limit " +
+            "is configured the result is `{ configured: false }`, which is a normal answer. To lower the limit use " +
+            `deeprelay_spending_limit_update. ${FREE}`,
+        inputSchema: {},
+        context: "getting the spending limit",
+        async call(_args, config) {
+            return orNotFound(async () => ({ configured: true, ...(await new sdk_1.BillingApi(config).getSpendingLimit()) }), () => ({ configured: false }));
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_subscription_get",
+        title: "Get the deeprelay subscription",
+        description: "Is the account subscribed, to which plan, and how much of the plan's quota is used this period? Call this to " +
+            `explain a plan-coverage verdict from deeprelay_inference_preflight. ${FREE}`,
+        inputSchema: {},
+        context: "getting the subscription",
+        async call(_args, config) {
+            return new sdk_1.BillingApi(config).getSubscription();
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_deposits_list",
+        title: "List crypto deposits",
+        description: `List the account's crypto deposits and the minimum deposit. ${DEPOSITS_NOTE} ${FREE}`,
+        inputSchema: {},
+        context: "listing crypto deposits",
+        async call(_args, config) {
+            return orNotFound(async () => ({ crypto_deposits_enabled: true, ...(await new sdk_1.BillingApi(config).listDeposits()) }), () => ({ crypto_deposits_enabled: false }));
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_deposits_get",
+        title: "Get a crypto deposit",
+        description: `Get one crypto deposit by id: status, chain, asset, amount and credited cents. ${DEPOSITS_NOTE} ` +
+            FREE,
+        inputSchema: {
+            id: zod_1.z.string().min(1).describe("Deposit id, as returned by deeprelay_deposits_list."),
+        },
+        context: "getting a crypto deposit",
+        async call(args, config) {
+            return orNotFound(async () => ({ crypto_deposits_enabled: true, ...(await new sdk_1.BillingApi(config).getDeposit({ id: args.id })) }), () => ({ crypto_deposits_enabled: false }));
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_referrals_get",
+        title: "Get the deeprelay referral link",
+        description: "Get the account's referral code and invite link, the program terms (reward amounts, qualifying spend, hold " +
+            `days) and the referral stats. Call this when the user asks how to invite someone or earn credit. ${FREE}`,
+        inputSchema: {},
+        context: "getting the referral program",
+        async call(_args, config) {
+            return new sdk_1.BillingApi(config).getReferral();
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_webhooks_list",
+        title: "List webhook endpoints",
+        description: "List the account's webhook endpoints: id, URL, subscribed event types and whether each is enabled. Pass " +
+            `\`cursor\` from \`nextCursor\` to page. ${NO_SECRET_NOTE} ${FREE}`,
+        inputSchema: {
+            cursor: zod_1.z.string().min(1).optional().describe("Page cursor from a previous result's nextCursor."),
+            limit: zod_1.z.number().int().min(1).max(100).optional().describe("Endpoints per page (1-100)."),
+        },
+        context: "listing webhook endpoints",
+        async call(args, config) {
+            const page = await new sdk_1.WebhooksApi(config).listWebhookEndpoints({ cursor: args.cursor, limit: args.limit });
+            return { ...page, data: page.data.map(withoutSecret) };
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_webhooks_get",
+        title: "Get a webhook endpoint",
+        description: `Get one webhook endpoint by id: URL, event types and enabled flag. ${NO_SECRET_NOTE} ${FREE}`,
+        inputSchema: {
+            id: zod_1.z.string().min(1).describe("Webhook endpoint id, as returned by deeprelay_webhooks_list."),
+        },
+        context: "getting a webhook endpoint",
+        async call(args, config) {
+            return withoutSecret(await new sdk_1.WebhooksApi(config).getWebhookEndpoint({ id: args.id }));
+        },
+    }),
+];
+/** The full read tier. Every name in roster READ_TOOLS appears here exactly once. */
+exports.readonlyTools = [...coreReadTools, ...billingReadTools, ...video_reads_js_1.videoReadTools];
+//# sourceMappingURL=index.js.map

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

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

package/dist/tools/readonly/video-reads.d.ts

@@ -0,0 +1,11 @@
+import { type VideoJob } from "@deeprelay/sdk";
+import type { ToolDefinition } from "../types.js";
+/** Where deeprelay_videos_content saves when no output_path is given. */
+export declare const VIDEO_TMP_DIR: string;
+export type SessionSettlement = "settled" | "released" | "pending" | "not_tracked";
+/**
+ * Settle (or release) this session's reservation for the job, then return the
+ * job's public fields plus what happened to the reservation.
+ */
+export declare function observeVideoJob(job: VideoJob): Record<string, unknown>;
+export declare const videoReadTools: ToolDefinition[];

package/dist/tools/readonly/video-reads.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.videoReadTools = exports.VIDEO_TMP_DIR = void 0;
+exports.observeVideoJob = observeVideoJob;
+// Video reads: list, get and content (Phase 104 D-02/D-07). Authored fresh (D-12).
+//
+// Video generation is asynchronous. deeprelay_videos_create reserves a floor
+// estimate against the session budget keyed by the video id, and the actual
+// charge (cost_cents) is only known once the job reaches `completed`. These
+// reads are the only place that reservation resolves: every job they observe
+// goes through observeVideoJob → settleVideo, which
+//
+//   completed                   → settles at cost_cents (the floor if absent)
+//   failed | cancelled | expired → releases the hold (never billed)
+//   queued | in_progress         → leaves it pending
+//
+// settleVideo drops the reservation on first settlement, so observing the same
+// finished job again reports "not_tracked" and never double-counts (T-104-21).
+//
+// Content is delivered as a file on the MCP host, never encoded inline: an MP4
+// can be tens of MB and would flood the agent's context (T-104-20). The stdio
+// server runs as the user, so an agent-chosen path is the user's own
+// filesystem; it must be absolute (T-104-19). The write uses flag "wx", so an
+// existing file is never overwritten: this tool advertises readOnlyHint, and
+// clobbering a file the agent happened to name would contradict that.
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const sdk_1 = require("@deeprelay/sdk");
+const zod_1 = require("zod");
+const budget_js_1 = require("../../guardrail/budget.js");
+const define_js_1 = require("./define.js");
+/** Where deeprelay_videos_content saves when no output_path is given. */
+exports.VIDEO_TMP_DIR = (0, node_path_1.join)((0, node_os_1.tmpdir)(), "deeprelay-mcp");
+const FREE = "Free: a read-only call with no charge and no confirmation.";
+function isTracked(videoId) {
+    return (0, budget_js_1.pendingVideoReservations)().some((r) => r.videoId === videoId);
+}
+function iso(unixSeconds) {
+    return typeof unixSeconds === "number" && Number.isFinite(unixSeconds)
+        ? new Date(unixSeconds * 1000).toISOString()
+        : null;
+}
+/**
+ * Settle (or release) this session's reservation for the job, then return the
+ * job's public fields plus what happened to the reservation.
+ */
+function observeVideoJob(job) {
+    const tracked = isTracked(job.id);
+    const outcome = (0, budget_js_1.settleVideo)(job.id, { status: job.status, costCents: job.costCents });
+    let settlement;
+    if (!tracked) {
+        settlement = "not_tracked";
+    }
+    else if (!outcome.settled) {
+        settlement = "pending";
+    }
+    else {
+        settlement = job.status === "completed" ? "settled" : "released";
+    }
+    return {
+        id: job.id,
+        model: job.model,
+        status: job.status,
+        progress: job.progress,
+        size: job.size ?? null,
+        seconds: job.seconds ?? null,
+        created_at: iso(job.createdAt),
+        completed_at: iso(job.completedAt),
+        expires_at: iso(job.expiresAt),
+        error: job.error ?? null,
+        cost_cents: job.costCents ?? null,
+        session_settlement: settlement,
+    };
+}
+/** A filesystem-safe default file name for a video id. */
+function defaultPath(videoId) {
+    const safe = videoId.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "_");
+    return (0, node_path_1.join)(exports.VIDEO_TMP_DIR, `${safe || "video"}.mp4`);
+}
+exports.videoReadTools = [
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_videos_list",
+        title: "List video generation jobs",
+        description: "List this account's video generation jobs, newest first, with status, progress and cost_cents once finished. " +
+            "Page with `after` (the last id seen). Observing a finished job here also settles this session's video " +
+            `reservation for it, like deeprelay_videos_get. ${FREE}`,
+        inputSchema: {
+            after: zod_1.z.string().min(1).optional().describe("Return jobs after this video id (pagination)."),
+            limit: zod_1.z.number().int().min(1).max(100).default(20).describe("Jobs per page (1-100)."),
+        },
+        context: "listing video jobs",
+        async call(args, config) {
+            const page = await new sdk_1.InferenceApi(config).listVideos({ after: args.after, limit: args.limit });
+            return { data: page.data.map((job) => observeVideoJob(job)), has_more: page.hasMore };
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_videos_get",
+        title: "Get a video generation job",
+        description: "Poll one video job: status (queued, in_progress, completed, failed, cancelled, expired), progress, and " +
+            "cost_cents once completed. Calling this after the job completes is what settles this session's video " +
+            "reservation and reports the actual charge; a failed, cancelled or expired job releases it unbilled. When " +
+            `status is completed, download the file with deeprelay_videos_content. ${FREE}`,
+        inputSchema: {
+            id: zod_1.z.string().min(1).describe("Video job id, as returned by deeprelay_videos_create."),
+        },
+        context: "getting a video job",
+        async call(args, config) {
+            return observeVideoJob(await new sdk_1.InferenceApi(config).getVideo({ id: args.id }));
+        },
+    }),
+    (0, define_js_1.defineTool)({
+        name: "deeprelay_videos_content",
+        title: "Download a generated video",
+        description: "Download a completed video's MP4 to a file on this machine and return its path and size (the video is never " +
+            "returned inline). Pass `output_path` as an absolute file path, or omit it to save under the system temp " +
+            "directory. It never overwrites an existing file: if the path exists the call is refused and you must choose a " +
+            "new path. Also settles this session's reservation for the job. Artifacts are kept for 24 hours after " +
+            `completion. ${FREE}`,
+        inputSchema: {
+            id: zod_1.z.string().min(1).describe("Video job id."),
+            output_path: zod_1.z
+                .string()
+                .min(1)
+                .refine((p) => (0, node_path_1.isAbsolute)(p), { message: "output_path must be an absolute file path" })
+                .optional()
+                .describe("Absolute path to write the MP4 to. Default: <system temp>/deeprelay-mcp/<id>.mp4"),
+        },
+        context: "downloading a video",
+        async call(args, config) {
+            const api = new sdk_1.InferenceApi(config);
+            const job = observeVideoJob(await api.getVideo({ id: args.id }));
+            if (job.status !== "completed") {
+                return {
+                    video_id: args.id,
+                    downloaded: false,
+                    status: job.status,
+                    session_settlement: job.session_settlement,
+                    next: job.status === "queued" || job.status === "in_progress"
+                        ? "The video is not ready. Poll deeprelay_videos_get until status is completed, then call this again."
+                        : `The video is ${String(job.status)} and has no downloadable content.`,
+                };
+            }
+            const blob = await api.getVideoContent({ id: args.id });
+            const bytes = Buffer.from(await blob.arrayBuffer());
+            const target = args.output_path ?? defaultPath(args.id);
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(target), { recursive: true });
+            try {
+                await (0, promises_1.writeFile)(target, bytes, { mode: 0o600, flag: "wx" });
+            }
+            catch (err) {
+                if (err?.code === "EEXIST") {
+                    throw new define_js_1.ReadRefusal(`Refused to download video ${args.id}: a file already exists at ${target} and this tool never ` +
+                        "overwrites files. Call deeprelay_videos_content again with a new absolute output_path.");
+                }
+                throw err;
+            }
+            return {
+                video_id: args.id,
+                saved_to: target,
+                bytes: bytes.length,
+                mime_type: "video/mp4",
+                cost_cents: job.cost_cents,
+                session_settlement: job.session_settlement,
+            };
+        },
+    }),
+];
+//# sourceMappingURL=video-reads.js.map

package/dist/tools/readonly/video-reads.js.map

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

package/dist/tools/result.d.ts

@@ -0,0 +1,22 @@
+import type { QuoteResult } from "../guardrail/types.js";
+import type { Env, ToolResult } from "./types.js";
+export interface OkOptions {
+    /** Merged into an object payload after sanitization. One-time reveals only. */
+    revealOnce?: Record<string, string>;
+    env?: Env;
+}
+/** Serialize a success payload as pretty JSON text, sanitized and redacted. */
+export declare function ok(payload: unknown, options?: OkOptions): ToolResult;
+/** Serialize a failure. The message is redacted again even if already mapped. */
+export declare function fail(err: unknown, env?: Env): ToolResult;
+/**
+ * Serialize a quote returned in place of execution. The agent must call the
+ * same tool again with `confirmation_token` (after the user agrees) to run it.
+ *
+ * `extra` carries tier-specific facts the agent needs to relay (the spend
+ * tier's `quote_kind` and proposed `session_budget_usd`). It is merged before
+ * the fixed fields, so it can never overwrite the token or the summary.
+ */
+export declare function quoteResult(q: QuoteResult, env?: Env, extra?: Record<string, unknown>): ToolResult;
+/** True for a guardrail QuoteResult (as opposed to an executed result). */
+export declare function isQuoteResult(v: unknown): v is QuoteResult;

package/dist/tools/result.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ok = ok;
+exports.fail = fail;
+exports.quoteResult = quoteResult;
+exports.isQuoteResult = isQuoteResult;
+const errors_js_1 = require("../errors.js");
+/** Serialize a success payload as pretty JSON text, sanitized and redacted. */
+function ok(payload, options = {}) {
+    let body = (0, errors_js_1.sanitizeCredentialFields)(payload === undefined ? null : payload);
+    if (options.revealOnce !== undefined) {
+        const base = typeof body === "object" && body !== null && !Array.isArray(body) ? body : { result: body };
+        body = { ...base, ...options.revealOnce };
+    }
+    const text = JSON.stringify(body, null, 2);
+    return { content: [{ type: "text", text: (0, errors_js_1.redactSecrets)(text, options.env) }] };
+}
+/** Serialize a failure. The message is redacted again even if already mapped. */
+function fail(err, env) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: (0, errors_js_1.redactSecrets)(message, env) }], isError: true };
+}
+/**
+ * Serialize a quote returned in place of execution. The agent must call the
+ * same tool again with `confirmation_token` (after the user agrees) to run it.
+ *
+ * `extra` carries tier-specific facts the agent needs to relay (the spend
+ * tier's `quote_kind` and proposed `session_budget_usd`). It is merged before
+ * the fixed fields, so it can never overwrite the token or the summary.
+ */
+function quoteResult(q, env, extra) {
+    const body = {
+        ...(extra ?? {}),
+        kind: "quote",
+        tier: q.tier,
+        tool: q.toolName,
+        summary: q.summary,
+        confirmation_token: q.confirmationToken,
+        expires_at: q.expiresAt,
+    };
+    if (q.estimateMicroCents !== undefined) {
+        body.estimate_micro_cents = q.estimateMicroCents;
+    }
+    if (q.isFloor !== undefined) {
+        body.is_floor = q.isFloor;
+    }
+    if (q.declined === true) {
+        body.declined = true;
+    }
+    return { content: [{ type: "text", text: (0, errors_js_1.redactSecrets)(JSON.stringify(body, null, 2), env) }] };
+}
+/** True for a guardrail QuoteResult (as opposed to an executed result). */
+function isQuoteResult(v) {
+    if (typeof v !== "object" || v === null) {
+        return false;
+    }
+    const candidate = v;
+    return (candidate.kind === "quote" &&
+        typeof candidate.confirmationToken === "string" &&
+        typeof candidate.expiresAt === "string" &&
+        typeof candidate.summary === "string");
+}
+//# sourceMappingURL=result.js.map

package/dist/tools/result.js.map

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