@deeprelay/mcp 0.0.1 → 0.1.1

package/dist/guardrail/elicitation.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientSupportsElicitation = clientSupportsElicitation;
+exports.buildPrompt = buildPrompt;
+exports.elicitConfirmation = elicitConfirmation;
+/** micro-cents per US dollar (1 dollar = 100 cents = 100,000,000 micro-cents). */
+const MICRO_CENTS_PER_DOLLAR = 100_000_000;
+/** True only when the connected client advertised the elicitation capability. */
+function clientSupportsElicitation(host) {
+    if (host === undefined || typeof host.elicitInput !== "function") {
+        return false;
+    }
+    try {
+        return Boolean(host.getClientCapabilities()?.elicitation);
+    }
+    catch {
+        return false;
+    }
+}
+function formatDollars(microCents) {
+    const dollars = microCents / MICRO_CENTS_PER_DOLLAR;
+    // Inference calls are often fractions of a cent, so keep up to six decimals
+    // but never fewer than two.
+    const fixed = dollars.toFixed(6).replace(/0+$/, "");
+    const [whole, frac = ""] = fixed.split(".");
+    return `$${whole}.${frac.padEnd(2, "0")}`;
+}
+/** The text the user reads: summary, price (if any), expiry, then the question. */
+function buildPrompt(quote, question) {
+    const lines = [quote.summary];
+    if (quote.estimateMicroCents !== undefined) {
+        lines.push(`Estimated cost: ${formatDollars(quote.estimateMicroCents)}.`);
+        if (quote.isFloor === true) {
+            lines.push("This is a floor, not a cap: the final charge can be higher.");
+        }
+    }
+    lines.push(`This confirmation expires at ${quote.expiresAt}.`);
+    lines.push("", question);
+    return lines.join("\n");
+}
+function confirmationRequest(quote, question) {
+    return {
+        mode: "form",
+        message: buildPrompt(quote, question),
+        requestedSchema: {
+            type: "object",
+            properties: {
+                confirm: {
+                    type: "boolean",
+                    title: "Confirm",
+                    description: "Yes — run this at the price shown above.",
+                },
+            },
+            required: ["confirm"],
+        },
+    };
+}
+/**
+ * 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.
+ */
+async function elicitConfirmation(host, quote, question) {
+    if (host === undefined || !clientSupportsElicitation(host)) {
+        return "unavailable";
+    }
+    let outcome;
+    try {
+        outcome = await host.elicitInput(confirmationRequest(quote, question));
+    }
+    catch {
+        return "unavailable";
+    }
+    if (outcome?.action === "accept" && outcome.content?.confirm === true) {
+        return "confirmed";
+    }
+    return "declined";
+}
+//# sourceMappingURL=elicitation.js.map

package/dist/guardrail/elicitation.js.map

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

package/dist/guardrail/estimate.d.ts

@@ -0,0 +1,67 @@
+import type { Modality } from "./types.js";
+/**
+ * Structural view of @deeprelay/sdk ModelPricing (camelCase). Rates named
+ * *Cents are whole cents. Rates named *Microcents are 1e-6 cent.
+ */
+export interface PricingLike {
+    inputPer1mTokensCents?: number;
+    outputPer1mTokensCents?: number;
+    cachedInputPer1mTokensMicrocents?: number;
+    perImageCents?: number;
+    perImageMicrocents?: number;
+    perMpxlMicrocents?: number;
+    perVideoMicrocents?: number;
+    perVideoSecondMicrocents?: number;
+}
+/** Agent-supplied request parameters that the estimate depends on. */
+export interface EstimateParams {
+    /** Chat: messages. Content may be a string or an array of `{ text }` parts. */
+    messages?: ReadonlyArray<{
+        content?: unknown;
+    } | string>;
+    /** Chat: the completion bound. Defaults to DEFAULT_MAX_TOKENS. */
+    maxTokens?: number;
+    /** Embeddings: input string(s). */
+    input?: string | ReadonlyArray<string>;
+    /** Image: number of images. Defaults to 1. */
+    n?: number;
+    /** Image: "WxH". Defaults to 1024x1024. */
+    size?: string;
+    /** Video: clip length in seconds. Defaults to 5. */
+    seconds?: number;
+}
+export interface Estimate {
+    /** Billed (whole-cent) micro-cents. */
+    microCents: number;
+    /** True when the number is a lower bound (video). */
+    isFloor: boolean;
+    /** False when the model publishes none of the rates this modality needs. */
+    pricingKnown: boolean;
+}
+export declare const CHARS_PER_TOKEN = 4;
+export declare const DEFAULT_MAX_TOKENS = 1024;
+export declare const DEFAULT_IMAGE_SIZE = "1024x1024";
+export declare const DEFAULT_VIDEO_SECONDS = 5;
+/** Prompt-token approximation: ceil(chars / 4) per string, at least 1 per non-empty string. */
+export declare function estimatePromptTokens(texts: ReadonlyArray<string>): number;
+/** Megapixels for a "WxH" size. Anything unparseable uses the default size. */
+export declare function megapixels(size: string | undefined): number;
+/** Estimate one invocation's billed cost before it runs. */
+export declare function estimateMicroCents(modality: Modality, params: EstimateParams, pricing: PricingLike): Estimate;
+/** Usage fields the API returns, per modality (camelCase SDK shapes). */
+export interface UsageLike {
+    /** Chat and embeddings. */
+    promptTokens?: number;
+    /** Chat. */
+    completionTokens?: number;
+    /** Image (ImagesResponseUsage). */
+    imageCount?: number;
+    /** Video (VideoJob, populated on completed). */
+    costCents?: number;
+}
+/**
+ * The billed actual cost of one completed invocation, from the API's usage
+ * fields. Falls back to the estimate when the usage the modality needs is
+ * missing. `params` supplies the image size for per-megapixel models.
+ */
+export declare function actualMicroCents(modality: Modality, usage: UsageLike | undefined, pricing: PricingLike, fallbackEstimateMicroCents: number, params?: EstimateParams): number;

package/dist/guardrail/estimate.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_VIDEO_SECONDS = exports.DEFAULT_IMAGE_SIZE = exports.DEFAULT_MAX_TOKENS = exports.CHARS_PER_TOKEN = void 0;
+exports.estimatePromptTokens = estimatePromptTokens;
+exports.megapixels = megapixels;
+exports.estimateMicroCents = estimateMicroCents;
+exports.actualMicroCents = actualMicroCents;
+// Per-modality cost estimator for the unified session budget (Phase 104 D-06).
+// Authored fresh (D-12).
+//
+// One dispatcher prices all four billable modalities from ModelPricing-shaped
+// rates. Every result goes through billedMicroCents, so it is rounded UP to
+// whole cents PER INVOCATION, the way the server bills. Never aggregate and then
+// round (D-82-A).
+//
+// The estimator is pure. It never fetches a rate. The caller passes the model's
+// pricing from the catalog read.
+//
+// Inputs from the agent (messages, n, size, seconds, max_tokens) are untrusted.
+// Non-finite or non-positive counts fall back to the defaults. For chat the
+// estimate is bounded by max_tokens. For video it is a FLOOR (isFloor: true),
+// because the catalog publishes a "from" price and the real cost arrives later
+// on VideoJob.costCents.
+const budget_js_1 = require("./budget.js");
+exports.CHARS_PER_TOKEN = 4;
+exports.DEFAULT_MAX_TOKENS = 1024;
+exports.DEFAULT_IMAGE_SIZE = "1024x1024";
+exports.DEFAULT_VIDEO_SECONDS = 5;
+const TOKENS_PER_RATE_UNIT = 1_000_000;
+function rate(v) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0;
+}
+function known(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+function positiveCount(v, fallback) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.ceil(v) : fallback;
+}
+/** Micro-cents for `tokens` at a cents-per-1M-tokens rate. */
+function tokenMicroCents(tokens, centsPer1m) {
+    return (tokens * rate(centsPer1m) * budget_js_1.MICRO_CENTS_PER_CENT) / TOKENS_PER_RATE_UNIT;
+}
+/** Prompt-token approximation: ceil(chars / 4) per string, at least 1 per non-empty string. */
+function estimatePromptTokens(texts) {
+    let total = 0;
+    for (const t of texts) {
+        if (typeof t !== "string" || t.length === 0)
+            continue;
+        total += Math.max(1, Math.ceil(t.length / exports.CHARS_PER_TOKEN));
+    }
+    return total;
+}
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => part && typeof part === "object" && typeof part.text === "string"
+            ? part.text
+            : "")
+            .join("");
+    }
+    return "";
+}
+function messageTexts(messages) {
+    if (!messages)
+        return [];
+    return messages.map((m) => (typeof m === "string" ? m : textOf(m?.content)));
+}
+function inputTexts(input) {
+    if (input === undefined)
+        return [];
+    return typeof input === "string" ? [input] : [...input];
+}
+/** Megapixels for a "WxH" size. Anything unparseable uses the default size. */
+function megapixels(size) {
+    const m = /^\s*(\d+)\s*[xX]\s*(\d+)\s*$/.exec(size ?? "");
+    const w = m ? Number(m[1]) : 0;
+    const h = m ? Number(m[2]) : 0;
+    if (w > 0 && h > 0)
+        return (w * h) / 1_000_000;
+    return (1024 * 1024) / 1_000_000; // DEFAULT_IMAGE_SIZE
+}
+function perImageMicroCents(pricing) {
+    if (known(pricing.perImageMicrocents))
+        return rate(pricing.perImageMicrocents);
+    if (known(pricing.perImageCents))
+        return rate(pricing.perImageCents) * budget_js_1.MICRO_CENTS_PER_CENT;
+    return undefined;
+}
+function imageRaw(count, size, pricing) {
+    const per = perImageMicroCents(pricing);
+    if (per !== undefined)
+        return count * per;
+    return count * rate(pricing.perMpxlMicrocents) * megapixels(size);
+}
+/** Estimate one invocation's billed cost before it runs. */
+function estimateMicroCents(modality, params, pricing) {
+    switch (modality) {
+        case "chat": {
+            const promptTokens = estimatePromptTokens(messageTexts(params.messages));
+            const maxTokens = positiveCount(params.maxTokens, exports.DEFAULT_MAX_TOKENS);
+            return {
+                microCents: (0, budget_js_1.billedMicroCents)(tokenMicroCents(promptTokens, pricing.inputPer1mTokensCents) +
+                    tokenMicroCents(maxTokens, pricing.outputPer1mTokensCents)),
+                isFloor: false,
+                pricingKnown: known(pricing.inputPer1mTokensCents) || known(pricing.outputPer1mTokensCents),
+            };
+        }
+        case "embeddings": {
+            const promptTokens = estimatePromptTokens(inputTexts(params.input));
+            return {
+                microCents: (0, budget_js_1.billedMicroCents)(tokenMicroCents(promptTokens, pricing.inputPer1mTokensCents)),
+                isFloor: false,
+                pricingKnown: known(pricing.inputPer1mTokensCents),
+            };
+        }
+        case "image": {
+            const n = positiveCount(params.n, 1);
+            return {
+                microCents: (0, budget_js_1.billedMicroCents)(imageRaw(n, params.size, pricing)),
+                isFloor: false,
+                pricingKnown: perImageMicroCents(pricing) !== undefined || known(pricing.perMpxlMicrocents),
+            };
+        }
+        case "video": {
+            const seconds = positiveCount(params.seconds, exports.DEFAULT_VIDEO_SECONDS);
+            const raw = known(pricing.perVideoMicrocents)
+                ? rate(pricing.perVideoMicrocents)
+                : rate(pricing.perVideoSecondMicrocents) * seconds;
+            return {
+                microCents: (0, budget_js_1.billedMicroCents)(raw),
+                isFloor: true,
+                pricingKnown: known(pricing.perVideoMicrocents) || known(pricing.perVideoSecondMicrocents),
+            };
+        }
+    }
+}
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0;
+}
+/**
+ * The billed actual cost of one completed invocation, from the API's usage
+ * fields. Falls back to the estimate when the usage the modality needs is
+ * missing. `params` supplies the image size for per-megapixel models.
+ */
+function actualMicroCents(modality, usage, pricing, fallbackEstimateMicroCents, params) {
+    const fallback = (0, budget_js_1.billedMicroCents)(fallbackEstimateMicroCents);
+    if (!usage)
+        return fallback;
+    switch (modality) {
+        case "chat":
+            if (!num(usage.promptTokens) || !num(usage.completionTokens))
+                return fallback;
+            return (0, budget_js_1.billedMicroCents)(tokenMicroCents(usage.promptTokens, pricing.inputPer1mTokensCents) +
+                tokenMicroCents(usage.completionTokens, pricing.outputPer1mTokensCents));
+        case "embeddings":
+            if (!num(usage.promptTokens))
+                return fallback;
+            return (0, budget_js_1.billedMicroCents)(tokenMicroCents(usage.promptTokens, pricing.inputPer1mTokensCents));
+        case "image":
+            if (!num(usage.imageCount))
+                return fallback;
+            return (0, budget_js_1.billedMicroCents)(imageRaw(usage.imageCount, params?.size, pricing));
+        case "video":
+            if (!num(usage.costCents))
+                return fallback;
+            return (0, budget_js_1.billedMicroCents)(usage.costCents * budget_js_1.MICRO_CENTS_PER_CENT);
+    }
+}
+//# sourceMappingURL=estimate.js.map

package/dist/guardrail/estimate.js.map

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

package/dist/guardrail/handshake.d.ts

@@ -0,0 +1,32 @@
+import type { Quote, QuoteResult } from "./types.js";
+/** Token lifetime: five minutes. */
+export declare const DEFAULT_TTL_MS = 300000;
+export interface HandshakeOptions {
+    /** Token lifetime in ms. Defaults to DEFAULT_TTL_MS. */
+    ttlMs?: number;
+    /** Clock injection for tests. Defaults to Date.now. */
+    now?: () => number;
+}
+/** Test-only: forget every pending token. */
+export declare function resetHandshakeStateForTests(): void;
+/**
+ * Discard a pending token without executing anything. Used when the user
+ * declines through elicitation: the quote they said no to must not stay
+ * redeemable for the rest of its TTL. Unknown or already-burned tokens are a
+ * no-op.
+ */
+export declare function revokeConfirmation(token: string): void;
+/**
+ * Normalize params for identity comparison: object keys deep-sorted, keys whose
+ * value is undefined dropped, arrays kept in order, primitives untouched (so the
+ * string "1" stays distinct from the number 1 once serialized).
+ */
+export declare function normalizeParams(params: Record<string, unknown>): unknown;
+/** Spend tier: price first, execute only on a redeemed token. */
+export declare function withSpendGuardrail<P extends Record<string, unknown>, R>(toolName: string, params: P & {
+    confirmation_token?: string;
+}, quoteFn: (p: P) => Promise<Quote>, executeFn: (p: P) => Promise<R>, opts?: HandshakeOptions): Promise<QuoteResult | R>;
+/** Write tier: describe the change first, execute only on a redeemed token. */
+export declare function withWriteConfirmation<P extends Record<string, unknown>, R>(toolName: string, params: P & {
+    confirmation_token?: string;
+}, quoteFn: (p: P) => Promise<Quote>, executeFn: (p: P) => Promise<R>, opts?: HandshakeOptions): Promise<QuoteResult | R>;

package/dist/guardrail/handshake.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TTL_MS = void 0;
+exports.resetHandshakeStateForTests = resetHandshakeStateForTests;
+exports.revokeConfirmation = revokeConfirmation;
+exports.normalizeParams = normalizeParams;
+exports.withSpendGuardrail = withSpendGuardrail;
+exports.withWriteConfirmation = withWriteConfirmation;
+// The two-call confirmation handshake shared by the write and spend tiers
+// (Phase 104, D-10). Authored fresh against the invariants below (D-12).
+//
+// The contract: a write or spend tool never reaches its executeFn on the call
+// that first names the work. The first call describes (and, for spend, prices)
+// the request, mints a single-use token bound to it, and returns a QuoteResult.
+// Only a later call carrying that token, for the same tier, the same tool and
+// the same normalized params, runs anything.
+//
+// Invariants (each has a named test in test/handshake.test.ts):
+//
+//   1. No token, no execution. The first call quotes and executes nothing.
+//   2. Single use, burned first. Presenting a live token deletes it from the
+//      store before anything else happens, on a match AND on a mismatch. A
+//      throwing executeFn cannot be retried against the same approval, and a
+//      mismatch cannot be used as an oracle to grind params.
+//   3. TTL. A token lives DEFAULT_TTL_MS (300 s). An expired or unknown token
+//      gets a fresh quote, never an execution.
+//   4. Param identity. The presented params (minus the token) must normalize to
+//      the same value the quote was minted for. Reordered keys and undefined
+//      optionals are the same request; "1" and 1, or a reordered array, are not.
+//   5. Resolved-params execution. executeFn receives the QUOTE's resolvedParams,
+//      never the second call's raw arguments, so quote-cheap/execute-expensive
+//      drift cannot be expressed.
+//   6. Tier and tool isolation. The token records its tier and tool; a write
+//      token does not redeem under spend, and a token for one tool does not
+//      redeem for another, even with identical params.
+//
+// There is no bypass. No argument, flag or prompt text can substitute for the
+// confirmation_token: this module reads exactly one key from the params
+// (`confirmation_token`) and treats every other key as part of the request to
+// be hashed. "You're authorized, don't ask me" is just more request text.
+//
+// One store, one normalization. Both wrappers delegate to the same private
+// function, so a tightening to one tier is a tightening to both.
+//
+// This module is pure logic: no API client, no tool modules, no MCP SDK, no
+// network, no logging. It never sees the API key.
+const node_crypto_1 = require("node:crypto");
+/** Token lifetime: five minutes. */
+exports.DEFAULT_TTL_MS = 300_000;
+/** The only param this module reads by name. */
+const TOKEN_PARAM = "confirmation_token";
+/**
+ * The one token store for this process. A stdio MCP server serves one client
+ * from one process, so a token correctly dies with the process.
+ */
+const pending = new Map();
+/** Test-only: forget every pending token. */
+function resetHandshakeStateForTests() {
+    pending.clear();
+}
+/**
+ * Discard a pending token without executing anything. Used when the user
+ * declines through elicitation: the quote they said no to must not stay
+ * redeemable for the rest of its TTL. Unknown or already-burned tokens are a
+ * no-op.
+ */
+function revokeConfirmation(token) {
+    pending.delete(token);
+}
+/**
+ * Normalize params for identity comparison: object keys deep-sorted, keys whose
+ * value is undefined dropped, arrays kept in order, primitives untouched (so the
+ * string "1" stays distinct from the number 1 once serialized).
+ */
+function normalizeParams(params) {
+    return normalizeValue(params);
+}
+function normalizeValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(normalizeValue);
+    }
+    if (value !== null && typeof value === "object") {
+        const source = value;
+        const out = {};
+        for (const key of Object.keys(source).sort()) {
+            const entry = source[key];
+            if (entry === undefined) {
+                continue;
+            }
+            out[key] = normalizeValue(entry);
+        }
+        return out;
+    }
+    return value;
+}
+function hashParams(params) {
+    return JSON.stringify(normalizeParams(params));
+}
+function stripToken(params) {
+    const { [TOKEN_PARAM]: _token, ...rest } = params;
+    return rest;
+}
+function pruneExpired(now) {
+    for (const [token, entry] of pending) {
+        if (entry.expiresAt <= now) {
+            pending.delete(token);
+        }
+    }
+}
+/** Spend tier: price first, execute only on a redeemed token. */
+async function withSpendGuardrail(toolName, params, quoteFn, executeFn, opts = {}) {
+    return withConfirmation("spend", toolName, params, quoteFn, executeFn, opts);
+}
+/** Write tier: describe the change first, execute only on a redeemed token. */
+async function withWriteConfirmation(toolName, params, quoteFn, executeFn, opts = {}) {
+    return withConfirmation("write", toolName, params, quoteFn, executeFn, opts);
+}
+async function withConfirmation(tier, toolName, params, quoteFn, executeFn, opts) {
+    const clock = opts.now ?? Date.now;
+    const ttlMs = opts.ttlMs ?? exports.DEFAULT_TTL_MS;
+    const request = stripToken(params);
+    const presented = params[TOKEN_PARAM];
+    if (typeof presented === "string" && presented !== "") {
+        const entry = pending.get(presented);
+        // Burn on any presentation, before any comparison or execution.
+        pending.delete(presented);
+        if (entry !== undefined && entry.expiresAt > clock()) {
+            const matches = entry.tier === tier && entry.toolName === toolName && entry.paramsHash === hashParams(request);
+            if (matches) {
+                return await executeFn(entry.resolvedParams);
+            }
+        }
+        // Unknown, expired, wrong tier, wrong tool or drifted params: re-quote.
+    }
+    pruneExpired(clock());
+    // quoteFn throwing propagates and mints nothing: no price shown, no token.
+    const quote = await quoteFn(request);
+    const token = (0, node_crypto_1.randomUUID)();
+    const expiresAt = clock() + ttlMs;
+    pending.set(token, {
+        tier,
+        toolName,
+        paramsHash: hashParams(request),
+        resolvedParams: quote.resolvedParams,
+        quote,
+        expiresAt,
+    });
+    const result = {
+        kind: "quote",
+        tier,
+        toolName,
+        summary: quote.summary,
+        confirmationToken: token,
+        expiresAt: new Date(expiresAt).toISOString(),
+    };
+    if (quote.estimateMicroCents !== undefined) {
+        result.estimateMicroCents = quote.estimateMicroCents;
+    }
+    if (quote.isFloor !== undefined) {
+        result.isFloor = quote.isFloor;
+    }
+    return result;
+}
+//# sourceMappingURL=handshake.js.map

package/dist/guardrail/handshake.js.map

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

package/dist/guardrail/types.d.ts

@@ -0,0 +1,61 @@
+/** The four billable inference modalities. One session budget covers all of them (D-06). */
+export type Modality = "chat" | "embeddings" | "image" | "video";
+/** What a write or spend tool proposes before it runs. */
+export interface Quote {
+    /** The one-line human summary the user confirms (e.g. "create a checkout link for plan X"). */
+    summary: string;
+    /** The exact parameters that will run. The confirmation token binds to these. */
+    resolvedParams: Record<string, unknown>;
+    /** Spend tools only: estimated cost in micro-cents. */
+    estimateMicroCents?: number;
+    /** True when the estimate is a floor, e.g. the video "from" price (D-07). */
+    isFloor?: boolean;
+}
+/** Returned to the agent in place of execution. The agent must call again with the token. */
+export interface QuoteResult {
+    kind: "quote";
+    tier: "write" | "spend";
+    toolName: string;
+    summary: string;
+    /** Single-use. Bound to toolName and resolvedParams. */
+    confirmationToken: string;
+    /** ISO-8601 expiry of the token. */
+    expiresAt: string;
+    estimateMicroCents?: number;
+    isFloor?: boolean;
+    /** Set when the user declined through elicitation. The agent must not retry unprompted. */
+    declined?: boolean;
+}
+/** Form-mode elicitation request, the only mode used. */
+export interface ElicitFormRequest {
+    mode?: "form";
+    message: string;
+    requestedSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/** How a client answers an elicitation. */
+export interface ElicitOutcome {
+    action: "accept" | "decline" | "cancel";
+    content?: Record<string, unknown>;
+}
+/**
+ * The server-side elicitation surface. It lives on the low-level Server
+ * (`server.server`), not on the per-request `extra` the tool callbacks receive.
+ */
+export interface ElicitationHost {
+    getClientCapabilities(): {
+        elicitation?: unknown;
+    } | undefined;
+    elicitInput(params: ElicitFormRequest): Promise<ElicitOutcome>;
+}
+/**
+ * Result of checking a spend quote against the session. The per-call ceiling
+ * is checked BEFORE the budget. That order is a safety property (D-08).
+ */
+export interface BudgetDecision {
+    verdict: "ok" | "needs_budget_handshake" | "over_ceiling";
+    reason: string;
+}

package/dist/guardrail/types.js

@@ -0,0 +1,10 @@
+"use strict";
+// Guardrail contracts: the quote, the two-call handshake, elicitation, and the
+// session budget (Phase 104 D-06..D-10). Types only.
+//
+// The field names are re-derived from what the Phase 80/82 guardrail proved
+// (quote summary plus resolved params, single-use confirmation token with a TTL,
+// ceiling checked before budget). They were read for their invariants only, and
+// no file is copied (D-12).
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/guardrail/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/guardrail/types.ts"],"names":[],"mappings":";AAAA,+EAA+E;AAC/E,qDAAqD;AACrD,EAAE;AACF,4EAA4E;AAC5E,iFAAiF;AACjF,gFAAgF;AAChF,4BAA4B"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type RegisteredRoster } from "./tools/index.js";
+/** Server name as MCP clients see it. */
+export declare const SERVER_NAME = "deeprelay";
+/** A bare server with no tools. Tests use it to register a partial surface. */
+export declare function createServer(): McpServer;
+export interface BuiltServer {
+    server: McpServer;
+    roster: RegisteredRoster;
+}
+/**
+ * The server a client talks to: every roster tool registered. Offline and
+ * instant; throws only if the registry has drifted from the roster.
+ */
+export declare function buildServer(): BuiltServer;
+/** Validate → build → connect → schedule the D-03 probe. */
+export declare function main(): Promise<void>;