@deeprelay/mcp 0.0.1 → 0.1.0

package/dist/errors.js

@@ -0,0 +1,307 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuoteUnavailableError = exports.CREDENTIAL_KEYS = exports.REDACTED = void 0;
+exports.redactSecrets = redactSecrets;
+exports.sanitizeCredentialFields = sanitizeCredentialFields;
+exports.httpStatusOf = httpStatusOf;
+exports.mapSdkError = mapSdkError;
+exports.readErrorEnvelope = readErrorEnvelope;
+exports.mapSdkErrorAsync = mapSdkErrorAsync;
+// The error and redaction funnel every tool result goes through
+// (Phase 104, D-12: authored fresh against the invariants below).
+//
+//  1. Agent-legible failures. The SDK throws the same ResponseError for every
+//     non-2xx. An agent that cannot tell "your key is bad" from "retry later"
+//     loops or gives up, so each status becomes one sentence that names the
+//     cause and the fix, and names deeprelay as the only party involved.
+//  2. No credential reaches the agent. Response bodies are untrusted text.
+//     Only a short summary field is ever lifted out of one, and every string
+//     this module returns has been through redactSecrets().
+//  3. No upstream provider name reaches the agent (INFPRIV-06). The server
+//     scrubs provider names from every /v1/* error before it leaves the wire,
+//     and that scrub is authoritative. This package ships to npm, so it
+//     deliberately carries no list of upstream names of its own; nothing here
+//     adds a provider name to a sentence.
+//
+// This module logs nothing. On a stdio MCP server stdout is the JSON-RPC
+// channel, and errors travel back to the caller as return values only.
+//
+// It is a leaf: it imports nothing from auth.ts, because auth.ts imports
+// redactSecrets from here. The two env-var names are restated below and the
+// tests assert they agree with auth.ts.
+const sdk_1 = require("@deeprelay/sdk");
+/** What replaces anything credential-shaped. */
+exports.REDACTED = "[REDACTED]";
+const KEY_ENV = "DEEPRELAY_API_KEY";
+const BASE_ENV = "DEEPRELAY_API_BASE";
+/** Named in network messages when no override is set. Mirrors auth.ts PROD_API_BASE. */
+const DEFAULT_BASE_FOR_MESSAGES = "https://api.deeprelay.ai/v1";
+/**
+ * deeprelay credentials: `deeprelay_live_…` and `deeprelay_test_…` keys.
+ * Narrow on purpose: other `deeprelay_`-prefixed strings (request ids such as
+ * `deeprelay_inf_…`, this server's own tool names) are not secrets and support
+ * needs them intact. Case-sensitive, so the env-var NAME `DEEPRELAY_API_KEY`
+ * in a remedy sentence is not itself redacted.
+ */
+const TOKEN_SHAPE = /deeprelay_(live|test)_[A-Za-z0-9_]+/g;
+/**
+ * Strip credentials out of arbitrary text. Two passes, because either alone
+ * leaves a hole:
+ *
+ *   1. the configured key's literal value, which catches a key of any shape
+ *      (a placeholder, another vendor's key pasted by mistake);
+ *   2. the deeprelay token shape, which catches a DIFFERENT key echoed back by
+ *      the API, one this process never held and so cannot match by value.
+ */
+function redactSecrets(text, env = process.env) {
+    let out = text;
+    const key = env[KEY_ENV];
+    if (key !== undefined && key.trim() !== "") {
+        out = out.split(key).join(exports.REDACTED);
+    }
+    return out.replace(TOKEN_SHAPE, exports.REDACTED);
+}
+/**
+ * Field names whose string VALUES are credential material. Both spellings,
+ * because SDK models are camelCase and raw bodies are snake_case. Exact match:
+ * a substring rule would also swallow ordinary fields such as `secret_rotated_at`
+ * style metadata or URLs the user needs.
+ *
+ * The webhook create tool reveals the new endpoint's signing secret exactly
+ * once through an explicit reveal path in tools/result.ts. Nothing else ever
+ * bypasses this set.
+ */
+exports.CREDENTIAL_KEYS = new Set([
+    "secret",
+    "signing_secret",
+    "signingSecret",
+    "api_key",
+    "apiKey",
+    "access_token",
+    "accessToken",
+    "authorization",
+]);
+/**
+ * Return a copy of `value` with every string under a CREDENTIAL_KEYS field
+ * replaced by REDACTED, at any depth and inside arrays. The input is never
+ * mutated. Non-string credential values (null, absent) are left alone so the
+ * agent is not told a secret exists where none does. Class instances such as
+ * Date are returned whole rather than flattened.
+ */
+function sanitizeCredentialFields(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeCredentialFields(item));
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+        return value;
+    }
+    const out = {};
+    for (const [field, item] of Object.entries(value)) {
+        out[field] =
+            exports.CREDENTIAL_KEYS.has(field) && typeof item === "string"
+                ? exports.REDACTED
+                : sanitizeCredentialFields(item);
+    }
+    return out;
+}
+/**
+ * A spend or write tool's quote step refusing to price a request. Throwing is
+ * what keeps a guardrail from minting a confirmation token for something that
+ * has no quote: no quote, no token, no execution. The mapper keeps this
+ * error's own wording.
+ */
+class QuoteUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "QuoteUnavailableError";
+    }
+}
+exports.QuoteUnavailableError = QuoteUnavailableError;
+/**
+ * The HTTP status of an SDK error, or undefined for anything that never got a
+ * response. Duck-typed as a fallback so a bundling or version skew that breaks
+ * instanceof cannot change behaviour. Exported so callers can branch on a
+ * status (e.g. a 404 spending limit meaning "none configured") consistently
+ * with the mapper.
+ */
+function httpStatusOf(err) {
+    if (err instanceof sdk_1.ResponseError) {
+        return err.response.status;
+    }
+    const status = err?.response?.status;
+    return typeof status === "number" ? status : undefined;
+}
+const MAX_DETAIL_LENGTH = 300;
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** Prepare API-supplied text for embedding: one line, bounded. */
+function cleanDetail(text) {
+    if (text === undefined) {
+        return undefined;
+    }
+    const cleaned = oneLine(text);
+    if (cleaned === "") {
+        return undefined;
+    }
+    return cleaned.length > MAX_DETAIL_LENGTH ? `${cleaned.slice(0, MAX_DETAIL_LENGTH - 1)}…` : cleaned;
+}
+function withDetails(sentence, details) {
+    const cleaned = cleanDetail(details);
+    return cleaned === undefined ? sentence : `${sentence} ${cleaned}`;
+}
+/** The base URL named in a network message, with any userinfo stripped. */
+function baseForMessages(env) {
+    const raw = env[BASE_ENV]?.trim();
+    if (raw === undefined || raw === "") {
+        return DEFAULT_BASE_FOR_MESSAGES;
+    }
+    try {
+        const url = new URL(raw);
+        url.username = "";
+        url.password = "";
+        return url.toString().replace(/\/+$/, "");
+    }
+    catch {
+        return `the configured ${BASE_ENV}`;
+    }
+}
+function formatZodIssues(err) {
+    const issues = err.issues;
+    if (!Array.isArray(issues) || issues.length === 0) {
+        return err instanceof Error ? err.message : "the arguments did not match the tool's schema";
+    }
+    return issues
+        .map((issue) => {
+        const { path, message } = issue;
+        const where = Array.isArray(path) && path.length > 0 ? path.map(String).join(".") : "(root)";
+        return `${where}: ${typeof message === "string" ? message : "invalid"}`;
+    })
+        .join("; ");
+}
+function statusSentence(status, context, details, code) {
+    switch (status) {
+        case 401:
+            // Deliberately carries no response detail: a 401 is about the
+            // credential, and echoing the body is the likeliest leak path.
+            return `deeprelay API key invalid or expired — check the ${KEY_ENV} environment variable in your MCP client configuration (while ${context}).`;
+        case 402: {
+            const base = `Insufficient balance — add credit at deeprelay.ai, then retry (while ${context}).`;
+            const withCode = code === "daily_limit_reached"
+                ? `${base} Code: daily_limit_reached — the account's daily spending limit has been reached.`
+                : base;
+            return withDetails(withCode, details);
+        }
+        case 403:
+            return withDetails(`Not permitted — this API key lacks the scope required for ${context}, or the account lacks the org-admin role.`, details);
+        case 404:
+            return withDetails(`Not found — ${context} referred to something that does not exist or is already gone.`, details);
+        case 409:
+            return withDetails(`Conflict — ${context} collided with the current state of the resource.`, details);
+        case 422:
+            return withDetails(`Invalid request — the deeprelay API rejected ${context}.`, details);
+        case 429:
+            return `Rate limited — wait a moment and retry (while ${context}). Do not retry in a tight loop.`;
+        default:
+            break;
+    }
+    if (status >= 500) {
+        return `deeprelay API error (${status}) while ${context} — retry later; if it persists check https://deeprelay.ai/status.`;
+    }
+    if (status >= 400) {
+        return withDetails(`Request rejected by the deeprelay API (HTTP ${status}) while ${context}.`, details);
+    }
+    return `Unexpected response from the deeprelay API (HTTP ${status}) while ${context}.`;
+}
+function noStatusSentence(err, context, env, details) {
+    const name = err instanceof Error ? err.name : undefined;
+    switch (name) {
+        case "ZodError":
+            return `Invalid arguments while ${context}: ${cleanDetail(formatZodIssues(err)) ?? "see the tool schema"}`;
+        case "StartupConfigError":
+        case "QuoteUnavailableError":
+            // Already a diagnosis in its own words; keep it.
+            return `${cleanDetail(err.message) ?? "Request refused."} (while ${context})`;
+        case "RequiredError": {
+            const field = err.field;
+            return `Missing required parameter${typeof field === "string" ? ` "${field}"` : ""} while ${context}.`;
+        }
+        case "FetchError":
+        case "AbortError":
+        case "TimeoutError":
+            return networkSentence(context, env);
+        default:
+            break;
+    }
+    if (name === "TypeError" && /fetch/i.test(err.message)) {
+        return networkSentence(context, env);
+    }
+    const raw = err instanceof Error ? err.message : String(err);
+    return withDetails(`Unexpected error while ${context}.`, details ?? raw);
+}
+function networkSentence(context, env) {
+    return `Could not reach the deeprelay API at ${baseForMessages(env)} while ${context} — check ${BASE_ENV} and your network.`;
+}
+/**
+ * Turn any thrown value into an agent-legible Error. Synchronous so the
+ * mapping is directly testable; tool handlers normally call mapSdkErrorAsync,
+ * which reads the response body first.
+ *
+ * `context` names what was being attempted ("listing models"), so a failure
+ * several calls deep stays attributable.
+ */
+function mapSdkError(err, context, options = {}) {
+    const env = options.env ?? process.env;
+    const status = httpStatusOf(err);
+    const sentence = status === undefined
+        ? noStatusSentence(err, context, env, options.details)
+        : statusSentence(status, context, options.details, options.code);
+    return new Error(redactSecrets(oneLine(sentence), env));
+}
+/**
+ * Read `{ code, message }` out of an SDK error's response body. Accepts both
+ * shapes the API returns: the OpenAI envelope `{ error: { code, message } }`
+ * and problem+json `{ code, detail }`. Fails closed: anything that is not
+ * recognisably one of those yields an empty envelope, never the raw body.
+ * Reads a clone, so the caller's Response is left unconsumed.
+ */
+async function readErrorEnvelope(err) {
+    const response = err?.response;
+    if (response === undefined || response === null || typeof response.clone !== "function") {
+        return {};
+    }
+    let body;
+    try {
+        body = JSON.parse(await response.clone().text());
+    }
+    catch {
+        return {};
+    }
+    if (typeof body !== "object" || body === null) {
+        return {};
+    }
+    const record = body;
+    const nested = record.error;
+    const source = typeof nested === "object" && nested !== null ? nested : record;
+    const code = typeof source.code === "string" && source.code !== "" ? source.code : undefined;
+    const messageField = source === record ? (record.detail ?? record.message) : source.message;
+    const message = typeof messageField === "string" && messageField.trim() !== "" ? messageField : undefined;
+    return { code, message };
+}
+/**
+ * The funnel tool handlers call: read the body once, then map. A 401 never
+ * uses the body (see statusSentence).
+ */
+async function mapSdkErrorAsync(err, context, env = process.env) {
+    const status = httpStatusOf(err);
+    if (status === undefined || status === 401) {
+        return mapSdkError(err, context, { env });
+    }
+    const envelope = await readErrorEnvelope(err);
+    return mapSdkError(err, context, { env, details: envelope.message, code: envelope.code });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/guardrail/budget.d.ts

@@ -0,0 +1,95 @@
+import type { BudgetDecision } from "./types.js";
+/** Micro-cents (1e-6 cent) per cent. Mirrors catalog.MicroCentsPerCent. */
+export declare const MICRO_CENTS_PER_CENT = 1000000;
+/** Default session budget: $5.00 (D-08). */
+export declare const SESSION_BUDGET_DEFAULT_CENTS = 500;
+/** Upper bound for a user-set session budget: $100.00. */
+export declare const SESSION_BUDGET_MAX_CENTS = 10000;
+/** Default per-call ceiling: $0.50 (D-08). */
+export declare const PER_CALL_CEILING_CENTS = 50;
+export declare const PER_CALL_CEILING_MICRO_CENTS: number;
+/**
+ * Round one invocation's raw cost UP to whole cents, expressed in micro-cents.
+ *
+ * The server bills each invocation as ceil(microcents / 1e6) cents
+ * (costCentsFor / db.CentsFromMicroCentsCeil). The rounding happens per call and
+ * always upward, so its error grows with CALL COUNT. Aggregating first and
+ * rounding once would under-count a session of sub-cent calls by up to 100x
+ * (the D-82-A regression). Every estimate and every actual goes through this
+ * function one invocation at a time.
+ *
+ * A non-positive or non-finite raw cost bills nothing, which mirrors the
+ * server's `if sum <= 0 { return 0 }`.
+ */
+export declare function billedMicroCents(rawMicroCents: number): number;
+export interface BudgetStatus {
+    approved: boolean;
+    limitCents: number;
+    ceilingMicroCents: number;
+    settledMicroCents: number;
+    pendingMicroCents: number;
+    /** limit - settled - pending, floored at 0. */
+    remainingMicroCents: number;
+}
+export declare function budgetStatus(): BudgetStatus;
+/**
+ * Approve a session budget. This is called only after the user confirms the
+ * budget handshake. The amount is clamped to [1, SESSION_BUDGET_MAX_CENTS].
+ * A fresh approval opens a fresh window: settled spend resets to 0.
+ * Outstanding reservations stay, because those calls may still bill.
+ * The per-call ceiling can also be set here. It is clamped the same way.
+ */
+export declare function approveBudget(cents: number, opts?: {
+    ceilingCents?: number;
+}): BudgetStatus;
+/**
+ * Decide whether a spend call with this estimate may run.
+ *
+ * Order (a safety property, D-08):
+ *   1. over_ceiling            estimate above the per-call ceiling, even when unapproved
+ *   2. needs_budget_handshake  no budget approved yet
+ *   3. needs_budget_handshake  settled actuals have reached the limit (the wall)
+ *   4. needs_budget_handshake  estimate exceeds remaining headroom (including pending)
+ *   5. ok
+ */
+export declare function checkCall(estimateMicroCents: number, opts?: {
+    ceilingMicroCents?: number;
+}): BudgetDecision;
+/** Reserve an estimate before the network call. It reduces headroom until settled or released. */
+export declare function recordEstimate(callId: string, microCents: number): void;
+/** Settle a call at its actual cost. Removes the reservation and adds the billed actual to settled spend. */
+export declare function reconcileActual(callId: string, actualMicroCents: number): void;
+/** Drop a reservation for a call that was never billed (error, cancel, failure). */
+export declare function releaseEstimate(callId: string): void;
+/**
+ * Hold a video job's floor estimate under callId and map the video id to it,
+ * so a later read (deeprelay_videos_get / _list) can settle it.
+ */
+export declare function registerPendingVideo(videoId: string, callId: string, floorMicroCents: number): void;
+export type VideoStatus = "queued" | "in_progress" | "completed" | "failed" | "cancelled" | "expired";
+/**
+ * Settle a video reservation from an observed job status.
+ *   completed -> reconcile at costCents (or the reserved floor if costCents is absent)
+ *   failed | cancelled | expired -> release. These are never billed.
+ *   queued | in_progress (or anything else) -> no change
+ */
+export declare function settleVideo(videoId: string, outcome: {
+    status: VideoStatus | string;
+    costCents?: number;
+}): {
+    settled: boolean;
+    microCents?: number;
+};
+/** One outstanding video reservation, keyed by the video id a read can settle. */
+export interface PendingVideoReservation {
+    videoId: string;
+    microCents: number;
+}
+/**
+ * The video reservations still waiting on a terminal status. Reported by
+ * deeprelay_auth_status and used by the video reads to tell "still pending"
+ * apart from "never tracked by this session".
+ */
+export declare function pendingVideoReservations(): PendingVideoReservation[];
+/** Test-only: restore the fresh-process state. */
+export declare function resetBudgetStateForTests(): void;

package/dist/guardrail/budget.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PER_CALL_CEILING_MICRO_CENTS = exports.PER_CALL_CEILING_CENTS = exports.SESSION_BUDGET_MAX_CENTS = exports.SESSION_BUDGET_DEFAULT_CENTS = exports.MICRO_CENTS_PER_CENT = void 0;
+exports.billedMicroCents = billedMicroCents;
+exports.budgetStatus = budgetStatus;
+exports.approveBudget = approveBudget;
+exports.checkCall = checkCall;
+exports.recordEstimate = recordEstimate;
+exports.reconcileActual = reconcileActual;
+exports.releaseEstimate = releaseEstimate;
+exports.registerPendingVideo = registerPendingVideo;
+exports.settleVideo = settleVideo;
+exports.pendingVideoReservations = pendingVideoReservations;
+exports.resetBudgetStateForTests = resetBudgetStateForTests;
+/** Micro-cents (1e-6 cent) per cent. Mirrors catalog.MicroCentsPerCent. */
+exports.MICRO_CENTS_PER_CENT = 1_000_000;
+/** Default session budget: $5.00 (D-08). */
+exports.SESSION_BUDGET_DEFAULT_CENTS = 500;
+/** Upper bound for a user-set session budget: $100.00. */
+exports.SESSION_BUDGET_MAX_CENTS = 10000;
+/** Default per-call ceiling: $0.50 (D-08). */
+exports.PER_CALL_CEILING_CENTS = 50;
+exports.PER_CALL_CEILING_MICRO_CENTS = exports.PER_CALL_CEILING_CENTS * exports.MICRO_CENTS_PER_CENT;
+/**
+ * Round one invocation's raw cost UP to whole cents, expressed in micro-cents.
+ *
+ * The server bills each invocation as ceil(microcents / 1e6) cents
+ * (costCentsFor / db.CentsFromMicroCentsCeil). The rounding happens per call and
+ * always upward, so its error grows with CALL COUNT. Aggregating first and
+ * rounding once would under-count a session of sub-cent calls by up to 100x
+ * (the D-82-A regression). Every estimate and every actual goes through this
+ * function one invocation at a time.
+ *
+ * A non-positive or non-finite raw cost bills nothing, which mirrors the
+ * server's `if sum <= 0 { return 0 }`.
+ */
+function billedMicroCents(rawMicroCents) {
+    if (!Number.isFinite(rawMicroCents) || rawMicroCents <= 0) {
+        return 0;
+    }
+    return Math.ceil(rawMicroCents / exports.MICRO_CENTS_PER_CENT) * exports.MICRO_CENTS_PER_CENT;
+}
+function freshState() {
+    return {
+        approved: false,
+        limitCents: exports.SESSION_BUDGET_DEFAULT_CENTS,
+        ceilingMicroCents: exports.PER_CALL_CEILING_MICRO_CENTS,
+        settledMicroCents: 0,
+        pending: new Map(),
+        pendingVideos: new Map(),
+    };
+}
+let state = freshState();
+function nonNegative(microCents) {
+    return Number.isFinite(microCents) && microCents > 0 ? microCents : 0;
+}
+function clampCents(cents, fallback) {
+    if (!Number.isFinite(cents))
+        return fallback;
+    return Math.min(exports.SESSION_BUDGET_MAX_CENTS, Math.max(1, Math.floor(cents)));
+}
+function dollars(microCents) {
+    return `$${(microCents / (exports.MICRO_CENTS_PER_CENT * 100)).toFixed(2)}`;
+}
+function pendingTotal() {
+    let sum = 0;
+    for (const v of state.pending.values())
+        sum += v;
+    return sum;
+}
+function budgetStatus() {
+    const limitMicroCents = state.limitCents * exports.MICRO_CENTS_PER_CENT;
+    const pendingMicroCents = pendingTotal();
+    return {
+        approved: state.approved,
+        limitCents: state.limitCents,
+        ceilingMicroCents: state.ceilingMicroCents,
+        settledMicroCents: state.settledMicroCents,
+        pendingMicroCents,
+        remainingMicroCents: Math.max(0, limitMicroCents - state.settledMicroCents - pendingMicroCents),
+    };
+}
+/**
+ * Approve a session budget. This is called only after the user confirms the
+ * budget handshake. The amount is clamped to [1, SESSION_BUDGET_MAX_CENTS].
+ * A fresh approval opens a fresh window: settled spend resets to 0.
+ * Outstanding reservations stay, because those calls may still bill.
+ * The per-call ceiling can also be set here. It is clamped the same way.
+ */
+function approveBudget(cents, opts) {
+    state.approved = true;
+    state.limitCents = clampCents(cents, exports.SESSION_BUDGET_DEFAULT_CENTS);
+    state.settledMicroCents = 0;
+    if (opts?.ceilingCents !== undefined) {
+        state.ceilingMicroCents = clampCents(opts.ceilingCents, exports.PER_CALL_CEILING_CENTS) * exports.MICRO_CENTS_PER_CENT;
+    }
+    return budgetStatus();
+}
+/**
+ * Decide whether a spend call with this estimate may run.
+ *
+ * Order (a safety property, D-08):
+ *   1. over_ceiling            estimate above the per-call ceiling, even when unapproved
+ *   2. needs_budget_handshake  no budget approved yet
+ *   3. needs_budget_handshake  settled actuals have reached the limit (the wall)
+ *   4. needs_budget_handshake  estimate exceeds remaining headroom (including pending)
+ *   5. ok
+ */
+function checkCall(estimateMicroCents, opts) {
+    const ceiling = opts?.ceilingMicroCents ?? state.ceilingMicroCents;
+    if (!Number.isFinite(estimateMicroCents)) {
+        return {
+            verdict: "over_ceiling",
+            reason: "This call could not be priced, so it must be confirmed on its own.",
+        };
+    }
+    const estimate = nonNegative(estimateMicroCents);
+    if (estimate > ceiling) {
+        return {
+            verdict: "over_ceiling",
+            reason: `This call is estimated at ${dollars(estimate)}, above the ${dollars(ceiling)} per-call ceiling. It must be confirmed on its own.`,
+        };
+    }
+    if (!state.approved) {
+        return {
+            verdict: "needs_budget_handshake",
+            reason: `No session budget is approved yet. Approve one (default ${dollars(exports.SESSION_BUDGET_DEFAULT_CENTS * exports.MICRO_CENTS_PER_CENT)}) before running spend tools.`,
+        };
+    }
+    const status = budgetStatus();
+    const limit = state.limitCents * exports.MICRO_CENTS_PER_CENT;
+    if (state.settledMicroCents >= limit) {
+        return {
+            verdict: "needs_budget_handshake",
+            reason: `The ${dollars(limit)} session budget is used up (${dollars(state.settledMicroCents)} settled). Approve a new budget to continue.`,
+        };
+    }
+    if (estimate > status.remainingMicroCents) {
+        return {
+            verdict: "needs_budget_handshake",
+            reason: `This call is estimated at ${dollars(estimate)}, but only ${dollars(status.remainingMicroCents)} of the ${dollars(limit)} session budget remains. Approve a new budget to continue.`,
+        };
+    }
+    return {
+        verdict: "ok",
+        reason: `Estimated ${dollars(estimate)}, within the remaining ${dollars(status.remainingMicroCents)} of the ${dollars(limit)} session budget.`,
+    };
+}
+/** Reserve an estimate before the network call. It reduces headroom until settled or released. */
+function recordEstimate(callId, microCents) {
+    state.pending.set(callId, nonNegative(microCents));
+}
+/** Settle a call at its actual cost. Removes the reservation and adds the billed actual to settled spend. */
+function reconcileActual(callId, actualMicroCents) {
+    state.pending.delete(callId);
+    dropVideoLinks(callId);
+    state.settledMicroCents += billedMicroCents(actualMicroCents);
+}
+/** Drop a reservation for a call that was never billed (error, cancel, failure). */
+function releaseEstimate(callId) {
+    state.pending.delete(callId);
+    dropVideoLinks(callId);
+}
+function dropVideoLinks(callId) {
+    for (const [videoId, linked] of state.pendingVideos) {
+        if (linked === callId)
+            state.pendingVideos.delete(videoId);
+    }
+}
+/**
+ * Hold a video job's floor estimate under callId and map the video id to it,
+ * so a later read (deeprelay_videos_get / _list) can settle it.
+ */
+function registerPendingVideo(videoId, callId, floorMicroCents) {
+    state.pending.set(callId, nonNegative(floorMicroCents));
+    state.pendingVideos.set(videoId, callId);
+}
+/**
+ * Settle a video reservation from an observed job status.
+ *   completed -> reconcile at costCents (or the reserved floor if costCents is absent)
+ *   failed | cancelled | expired -> release. These are never billed.
+ *   queued | in_progress (or anything else) -> no change
+ */
+function settleVideo(videoId, outcome) {
+    const callId = state.pendingVideos.get(videoId);
+    if (callId === undefined) {
+        return { settled: false };
+    }
+    switch (outcome.status) {
+        case "completed": {
+            const reserved = state.pending.get(callId) ?? 0;
+            const cost = outcome.costCents;
+            const actual = typeof cost === "number" && Number.isFinite(cost) && cost >= 0
+                ? cost * exports.MICRO_CENTS_PER_CENT
+                : reserved;
+            const billed = billedMicroCents(actual);
+            reconcileActual(callId, billed);
+            return { settled: true, microCents: billed };
+        }
+        case "failed":
+        case "cancelled":
+        case "expired":
+            releaseEstimate(callId);
+            return { settled: true, microCents: 0 };
+        default:
+            return { settled: false };
+    }
+}
+/**
+ * The video reservations still waiting on a terminal status. Reported by
+ * deeprelay_auth_status and used by the video reads to tell "still pending"
+ * apart from "never tracked by this session".
+ */
+function pendingVideoReservations() {
+    const out = [];
+    for (const [videoId, callId] of state.pendingVideos) {
+        out.push({ videoId, microCents: state.pending.get(callId) ?? 0 });
+    }
+    return out;
+}
+/** Test-only: restore the fresh-process state. */
+function resetBudgetStateForTests() {
+    state = freshState();
+}
+//# sourceMappingURL=budget.js.map

package/dist/guardrail/budget.js.map

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

package/dist/guardrail/elicitation.d.ts

@@ -0,0 +1,12 @@
+import type { ElicitationHost, QuoteResult } from "./types.js";
+export type ElicitationAnswer = "confirmed" | "declined" | "unavailable";
+/** True only when the connected client advertised the elicitation capability. */
+export declare function clientSupportsElicitation(host?: ElicitationHost): boolean;
+/** The text the user reads: summary, price (if any), expiry, then the question. */
+export declare function buildPrompt(quote: QuoteResult, question: string): string;
+/**
+ * Ask the user to confirm a quote. Executes nothing. Returns "unavailable" when
+ * the client cannot be asked or the ask fails, "confirmed" only for an explicit
+ * accept with `confirm === true`, and "declined" for everything else.
+ */
+export declare function elicitConfirmation(host: ElicitationHost | undefined, quote: QuoteResult, question: string): Promise<ElicitationAnswer>;