@deeprelay/mcp 0.0.1 → 0.1.1

package/dist/tools/readonly/index.js

@@ -0,0 +1,286 @@
+"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 GET mapped to one @deeprelay/sdk method (D-05; the usage
+// tool calls it once per modality when unfiltered, see usage.ts),
+// 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 usage_js_1 = require("./usage.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 key problem. It uses the unauthenticated liveness endpoint, so a wrong or revoked key does not affect it. ${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 inference usage",
+        description: "How much serverless inference has this account used and spent, over time? Returns time-bucketed inference " +
+            "usage (hour, day, week or month buckets; default day over the last 30 days), one row per bucket, modality " +
+            "and model, with cost in cents and token/image counts, plus `total_cost_cents` and per-modality subtotals " +
+            "(`by_modality`). Filter with `modality` (chat, image, video, embedding) and/or `model`; with neither it " +
+            "covers all four modalities. Pages are followed automatically; `truncated: true` means the window was too " +
+            "large, so narrow `start`/`end`. Use this to answer spend questions about past days; for this session's " +
+            `spend use deeprelay_auth_status. ${FREE}`,
+        inputSchema: usage_js_1.usageInputSchema,
+        context: "getting usage",
+        async call(args, config) {
+            return (0, usage_js_1.getInferenceUsage)(args, config);
+        },
+    }),
+];
+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/usage.d.ts

@@ -0,0 +1,29 @@
+import { type Configuration } from "@deeprelay/sdk";
+import { z } from "zod";
+/** Rows per page requested from the API (its maximum). */
+export declare const USAGE_PAGE_SIZE = 100;
+/** Pages followed per query before the result is reported as truncated. */
+export declare const USAGE_MAX_PAGES = 10;
+/** Every modality, in the order the fan-out queries them. */
+export declare const USAGE_MODALITIES: ("chat" | "image" | "video" | "embedding")[];
+export declare const usageInputSchema: {
+    modality: z.ZodOptional<z.ZodEnum<{
+        readonly Chat: "chat";
+        readonly Image: "image";
+        readonly Video: "video";
+        readonly Embedding: "embedding";
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+    bucket: z.ZodDefault<z.ZodEnum<{
+        readonly Hour: "hour";
+        readonly Day: "day";
+        readonly Week: "week";
+        readonly Month: "month";
+    }>>;
+    start: z.ZodOptional<z.ZodISODateTime>;
+    end: z.ZodOptional<z.ZodISODateTime>;
+};
+type UsageArgs = z.infer<z.ZodObject<typeof usageInputSchema>>;
+/** Read inference usage: one query when filtered, one per modality otherwise. */
+export declare function getInferenceUsage(args: UsageArgs, config: Configuration): Promise<Record<string, unknown>>;
+export {};

package/dist/tools/readonly/usage.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usageInputSchema = exports.USAGE_MODALITIES = exports.USAGE_MAX_PAGES = exports.USAGE_PAGE_SIZE = void 0;
+exports.getInferenceUsage = getInferenceUsage;
+// deeprelay_usage_get: serverless inference usage (Phase 104 follow-up).
+//
+// GET /v1/usage has two row shapes. With `modality` or `model` set it returns
+// inference-usage rows (one per bucket × modality × model); with neither it
+// returns GPU-instance usage, which deeprelay does not surface (no GPU supply
+// on the platform), so an unfiltered call reads as "no usage" even for an
+// account that spent money on inference. There is no single call for every
+// modality, so with no filter this tool asks once per modality and merges.
+//
+// It never sends `group_by` (instance/GPU split) and drops `gpu_seconds`,
+// which is always 0 on inference rows.
+const sdk_1 = require("@deeprelay/sdk");
+const zod_1 = require("zod");
+/** Rows per page requested from the API (its maximum). */
+exports.USAGE_PAGE_SIZE = 100;
+/** Pages followed per query before the result is reported as truncated. */
+exports.USAGE_MAX_PAGES = 10;
+/** Every modality, in the order the fan-out queries them. */
+exports.USAGE_MODALITIES = Object.values(sdk_1.ListUsageModalityEnum);
+exports.usageInputSchema = {
+    modality: zod_1.z
+        .enum(sdk_1.ListUsageModalityEnum)
+        .optional()
+        .describe("Only this modality (chat, image, video or embedding). Omit for all four."),
+    model: zod_1.z.string().min(1).optional().describe("Only this model id, as returned by deeprelay_models_list."),
+    bucket: zod_1.z.enum(sdk_1.ListUsageBucketEnum).default("day").describe("Bucket width (hour, day, week or month)."),
+    start: zod_1.z.iso
+        .datetime({ offset: true })
+        .optional()
+        .describe("ISO-8601 start of the window (inclusive). Default: 30 days before end."),
+    end: zod_1.z.iso.datetime({ offset: true }).optional().describe("ISO-8601 end of the window (exclusive). Default: now."),
+};
+/** Sum cents without binary-float noise (costs can be fractional cents). */
+function addCents(a, b) {
+    return Math.round((a + b) * 1e6) / 1e6;
+}
+function toRow(b, fallbackModality) {
+    const start = b.bucketStart instanceof Date ? b.bucketStart.toISOString() : String(b.bucketStart);
+    return {
+        bucket_start: start,
+        modality: b.modality ?? fallbackModality ?? null,
+        model: b.model ?? null,
+        cost_cents: b.costCents,
+        prompt_tokens: b.promptTokens ?? null,
+        completion_tokens: b.completionTokens ?? null,
+        image_count: b.imageCount ?? null,
+    };
+}
+/** One filtered query, following cursors up to USAGE_MAX_PAGES. */
+async function fetchAll(api, args, filter) {
+    const rows = [];
+    let cursor;
+    for (let pageNo = 0; pageNo < exports.USAGE_MAX_PAGES; pageNo += 1) {
+        const page = await api.listUsage({
+            bucket: args.bucket,
+            start: args.start === undefined ? undefined : new Date(args.start),
+            end: args.end === undefined ? undefined : new Date(args.end),
+            cursor,
+            limit: exports.USAGE_PAGE_SIZE,
+            modality: filter.modality,
+            model: filter.model,
+        });
+        rows.push(...page.data.map((b) => toRow(b, filter.modality)));
+        if (page.nextCursor === null || page.nextCursor === undefined || page.nextCursor === "") {
+            return { rows, truncated: false };
+        }
+        cursor = page.nextCursor;
+    }
+    return { rows, truncated: true };
+}
+/** Read inference usage: one query when filtered, one per modality otherwise. */
+async function getInferenceUsage(args, config) {
+    const api = new sdk_1.UsageApi(config);
+    const filtered = args.modality !== undefined || args.model !== undefined;
+    const queries = filtered
+        ? [{ modality: args.modality, model: args.model }]
+        : exports.USAGE_MODALITIES.map((modality) => ({ modality }));
+    const results = await Promise.all(queries.map((q) => fetchAll(api, args, q)));
+    const rows = results.flatMap((r) => r.rows);
+    // Newest bucket first (the API's order), then by modality and model.
+    rows.sort((a, b) => b.bucket_start.localeCompare(a.bucket_start) ||
+        (a.modality ?? "").localeCompare(b.modality ?? "") ||
+        (a.model ?? "").localeCompare(b.model ?? ""));
+    const byModality = {};
+    // With no filter every modality was asked, so report the zeros too.
+    if (!filtered) {
+        for (const m of exports.USAGE_MODALITIES)
+            byModality[m] = { cost_cents: 0, rows: 0 };
+    }
+    let total = 0;
+    for (const row of rows) {
+        const key = row.modality ?? "unknown";
+        const sub = (byModality[key] ??= { cost_cents: 0, rows: 0 });
+        sub.cost_cents = addCents(sub.cost_cents, row.cost_cents);
+        sub.rows += 1;
+        total = addCents(total, row.cost_cents);
+    }
+    const truncatedQueries = queries.filter((_, i) => results[i].truncated);
+    const truncated = truncatedQueries.length > 0;
+    return {
+        usage_kind: "inference",
+        note: "Serverless inference usage (what this account is billed for), from GET /v1/usage filtered by modality/model. " +
+            (filtered
+                ? "One filtered query."
+                : `No modality or model was given, so this merges one query per modality (${exports.USAGE_MODALITIES.join(", ")}).`) +
+            (truncated
+                ? ` TRUNCATED: stopped after ${exports.USAGE_MAX_PAGES} pages of ${exports.USAGE_PAGE_SIZE} rows for ` +
+                    truncatedQueries.map((q) => q.modality ?? q.model ?? "the query").join(", ") +
+                    "; totals cover only the rows returned. Narrow start/end or use a wider bucket."
+                : ""),
+        filter: { modality: args.modality ?? null, model: args.model ?? null },
+        bucket: args.bucket,
+        start: args.start ?? null,
+        end: args.end ?? null,
+        total_cost_cents: total,
+        total_cost_dollars: `$${(total / 100).toFixed(2)}`,
+        by_modality: byModality,
+        truncated,
+        rows,
+    };
+}
+//# sourceMappingURL=usage.js.map

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

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