@paybond/kit 0.9.8 → 0.11.0

package/dist/mcp/tool-surface.js

@@ -0,0 +1,17 @@
+import { buildMcpServerEntry, defaultMcpServerCommand, serializeMcpInstallPayload, } from "../cli/mcp-install.js";
+/**
+ * Framework runner helper for external MCP hosts (Claude Desktop, Codex, generic stdio).
+ *
+ * The bound {@link PaybondAgentRun} establishes tenant/intent context for your app;
+ * the returned `serverConfig` is the stdio entry coding-agent hosts consume via
+ * `PAYBOND_ENV_FILE` (never raw API keys in host config files).
+ */
+export function createPaybondMcpToolSurface(_run, options) {
+    const envFile = options?.envFile?.trim() || ".env.local";
+    const serverCommand = options?.serverCommand ?? defaultMcpServerCommand();
+    const serverConfig = buildMcpServerEntry(envFile, serverCommand, options?.toolPolicy);
+    return {
+        serverConfig,
+        installPayload: (format = "json") => serializeMcpInstallPayload(format, serverConfig),
+    };
+}

package/dist/mcp-capability-token-cache.d.ts

@@ -0,0 +1,24 @@
+export declare const MCP_CAPABILITY_TOKEN_TTL_ENV = "PAYBOND_MCP_CAPABILITY_TOKEN_TTL_SEC";
+export declare const MCP_CAPABILITY_TOKEN_CACHE_MAX_ENV = "PAYBOND_MCP_CAPABILITY_TOKEN_CACHE_MAX";
+export declare const DEFAULT_MCP_CAPABILITY_TOKEN_TTL_SEC = 900;
+export declare const DEFAULT_MCP_CAPABILITY_TOKEN_CACHE_MAX = 64;
+/** MCP tools that mint or return funded intent capability tokens from Harbor. */
+export declare const MCP_CAPABILITY_TOKEN_STORE_TOOLS: readonly ["paybond_bootstrap_sandbox_guardrail", "paybond_create_intent", "paybond_create_spend_intent", "paybond_fund_intent"];
+export type McpCapabilityTokenStoreTool = (typeof MCP_CAPABILITY_TOKEN_STORE_TOOLS)[number];
+/** Return true when an MCP tool response may populate the runtime token cache. */
+export declare function mcpToolStoresCapabilityToken(toolName: string): boolean;
+export type McpCapabilityTokenCacheConfig = {
+    ttlSec: number;
+    maxEntries: number;
+};
+export declare class McpCapabilityTokenCache {
+    private readonly ttlSec;
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(config?: McpCapabilityTokenCacheConfig);
+    store(intentId: string, token: string): void;
+    resolve(intentId: string): string | undefined;
+    private evictExpired;
+    private evictOverflow;
+}
+export declare function parseMcpCapabilityTokenCacheConfig(env?: Record<string, string | undefined>): McpCapabilityTokenCacheConfig;

package/dist/mcp-capability-token-cache.js

@@ -0,0 +1,101 @@
+export const MCP_CAPABILITY_TOKEN_TTL_ENV = "PAYBOND_MCP_CAPABILITY_TOKEN_TTL_SEC";
+export const MCP_CAPABILITY_TOKEN_CACHE_MAX_ENV = "PAYBOND_MCP_CAPABILITY_TOKEN_CACHE_MAX";
+export const DEFAULT_MCP_CAPABILITY_TOKEN_TTL_SEC = 900;
+export const DEFAULT_MCP_CAPABILITY_TOKEN_CACHE_MAX = 64;
+const MIN_MCP_CAPABILITY_TOKEN_TTL_SEC = 60;
+const MAX_MCP_CAPABILITY_TOKEN_TTL_SEC = 86_400;
+const MIN_MCP_CAPABILITY_TOKEN_CACHE_MAX = 1;
+const MAX_MCP_CAPABILITY_TOKEN_CACHE_MAX = 512;
+/** MCP tools that mint or return funded intent capability tokens from Harbor. */
+export const MCP_CAPABILITY_TOKEN_STORE_TOOLS = [
+    "paybond_bootstrap_sandbox_guardrail",
+    "paybond_create_intent",
+    "paybond_create_spend_intent",
+    "paybond_fund_intent",
+];
+const MCP_CAPABILITY_TOKEN_STORE_TOOL_SET = new Set(MCP_CAPABILITY_TOKEN_STORE_TOOLS);
+/** Return true when an MCP tool response may populate the runtime token cache. */
+export function mcpToolStoresCapabilityToken(toolName) {
+    return MCP_CAPABILITY_TOKEN_STORE_TOOL_SET.has(toolName.trim());
+}
+export class McpCapabilityTokenCache {
+    ttlSec;
+    maxEntries;
+    entries = new Map();
+    constructor(config) {
+        this.ttlSec = config?.ttlSec ?? DEFAULT_MCP_CAPABILITY_TOKEN_TTL_SEC;
+        this.maxEntries = config?.maxEntries ?? DEFAULT_MCP_CAPABILITY_TOKEN_CACHE_MAX;
+    }
+    store(intentId, token) {
+        const key = intentId.trim();
+        const value = token.trim();
+        if (!key || !value) {
+            return;
+        }
+        this.evictExpired();
+        this.entries.set(key, { token: value, storedAtMs: Date.now() });
+        this.evictOverflow();
+    }
+    resolve(intentId) {
+        this.evictExpired();
+        const key = String(intentId).trim();
+        const entry = this.entries.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        if (Date.now() - entry.storedAtMs > this.ttlSec * 1000) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.token;
+    }
+    evictExpired() {
+        const now = Date.now();
+        const ttlMs = this.ttlSec * 1000;
+        for (const [key, entry] of this.entries) {
+            if (now - entry.storedAtMs > ttlMs) {
+                this.entries.delete(key);
+            }
+        }
+    }
+    evictOverflow() {
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined) {
+                break;
+            }
+            this.entries.delete(oldest);
+        }
+    }
+}
+export function parseMcpCapabilityTokenCacheConfig(env = process.env) {
+    const ttlRaw = env[MCP_CAPABILITY_TOKEN_TTL_ENV]?.trim();
+    const maxRaw = env[MCP_CAPABILITY_TOKEN_CACHE_MAX_ENV]?.trim();
+    let ttlSec = DEFAULT_MCP_CAPABILITY_TOKEN_TTL_SEC;
+    if (ttlRaw) {
+        const parsed = Number.parseFloat(ttlRaw);
+        if (!Number.isFinite(parsed)) {
+            throw new Error(`invalid ${MCP_CAPABILITY_TOKEN_TTL_ENV} (expected a number of seconds)`);
+        }
+        if (parsed < MIN_MCP_CAPABILITY_TOKEN_TTL_SEC ||
+            parsed > MAX_MCP_CAPABILITY_TOKEN_TTL_SEC) {
+            throw new Error(`invalid ${MCP_CAPABILITY_TOKEN_TTL_ENV} (expected ${MIN_MCP_CAPABILITY_TOKEN_TTL_SEC}-${MAX_MCP_CAPABILITY_TOKEN_TTL_SEC} seconds)`);
+        }
+        ttlSec = parsed;
+    }
+    let maxEntries = DEFAULT_MCP_CAPABILITY_TOKEN_CACHE_MAX;
+    if (maxRaw) {
+        const parsed = Number.parseInt(maxRaw, 10);
+        if (!Number.isInteger(parsed)) {
+            throw new Error(`invalid ${MCP_CAPABILITY_TOKEN_CACHE_MAX_ENV} (expected an integer)`);
+        }
+        if (parsed < MIN_MCP_CAPABILITY_TOKEN_CACHE_MAX ||
+            parsed > MAX_MCP_CAPABILITY_TOKEN_CACHE_MAX) {
+            throw new Error(`invalid ${MCP_CAPABILITY_TOKEN_CACHE_MAX_ENV} (expected ${MIN_MCP_CAPABILITY_TOKEN_CACHE_MAX}-${MAX_MCP_CAPABILITY_TOKEN_CACHE_MAX})`);
+        }
+        maxEntries = parsed;
+    }
+    return { ttlSec, maxEntries };
+}

package/dist/mcp-evidence-policy.d.ts

@@ -0,0 +1,48 @@
+import { type CompletionEvidenceValidationReport } from "./completion-validate-evidence.js";
+export type McpEvidencePolicy = "strict" | "off";
+export declare const MCP_EVIDENCE_POLICY_ENV = "PAYBOND_MCP_EVIDENCE_POLICY";
+export declare const DEFAULT_MCP_EVIDENCE_POLICY: McpEvidencePolicy;
+export declare const EVIDENCE_SUBMIT_TOOL_NAMES: Set<string>;
+export declare class McpEvidencePolicyError extends Error {
+    constructor(message: string);
+}
+export declare function parseMcpEvidencePolicy(raw: string | undefined): McpEvidencePolicy;
+export declare function completionEvidenceValidationOk(report: CompletionEvidenceValidationReport): boolean;
+export declare function evidenceValidationGateKey(input: {
+    presetId: string;
+    vendorPayload?: Record<string, unknown>;
+    canonicalPayload?: Record<string, unknown>;
+}): string;
+export declare function extractHarborEvidenceValidationInput(body: Record<string, unknown>, completionPresetId?: string): {
+    presetId: string;
+    vendorPayload?: Record<string, unknown>;
+    canonicalPayload?: Record<string, unknown>;
+};
+export declare function extractSandboxGuardrailValidationInput(input: {
+    payload?: Record<string, unknown>;
+    completionPresetId?: string;
+}): {
+    presetId: string;
+    vendorPayload?: Record<string, unknown>;
+    canonicalPayload?: Record<string, unknown>;
+};
+export declare class McpEvidenceValidationGate {
+    readonly policy: McpEvidencePolicy;
+    private readonly passes;
+    constructor(policy?: McpEvidencePolicy);
+    recordPass(gateKey: string): void;
+    hasPass(gateKey: string): boolean;
+    requirePass(input: {
+        presetId: string;
+        vendorPayload?: Record<string, unknown>;
+        canonicalPayload?: Record<string, unknown>;
+    }): void;
+    validateAndRecord(input: {
+        presetId: string;
+        vendorPayload?: Record<string, unknown>;
+        canonicalPayload?: Record<string, unknown>;
+        frozenVendorApiVersion?: string;
+        frozenVendorSchemaDigestHex?: string;
+        frozenCanonicalSchemaDigestHex?: string;
+    }): CompletionEvidenceValidationReport;
+}

package/dist/mcp-evidence-policy.js

@@ -0,0 +1,117 @@
+import { validateCompletionEvidence, } from "./completion-validate-evidence.js";
+import { jsonValueDigest } from "./json-digest.js";
+export const MCP_EVIDENCE_POLICY_ENV = "PAYBOND_MCP_EVIDENCE_POLICY";
+export const DEFAULT_MCP_EVIDENCE_POLICY = "strict";
+export const EVIDENCE_SUBMIT_TOOL_NAMES = new Set([
+    "paybond_submit_evidence",
+    "paybond_submit_spend_evidence",
+    "paybond_submit_sandbox_guardrail_evidence",
+]);
+export class McpEvidencePolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpEvidencePolicyError";
+    }
+}
+export function parseMcpEvidencePolicy(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (!value) {
+        return DEFAULT_MCP_EVIDENCE_POLICY;
+    }
+    if (value === "strict" || value === "off") {
+        return value;
+    }
+    throw new Error("invalid PAYBOND_MCP_EVIDENCE_POLICY (expected strict|off)");
+}
+export function completionEvidenceValidationOk(report) {
+    return report.drift_kinds.length === 0;
+}
+export function evidenceValidationGateKey(input) {
+    const presetId = input.presetId.trim();
+    if (!presetId) {
+        throw new Error("completion preset id is required for evidence validation");
+    }
+    const digest = jsonValueDigest({
+        preset_id: presetId,
+        vendor_payload: input.vendorPayload,
+        canonical_payload: input.canonicalPayload,
+    });
+    return Buffer.from(digest).toString("hex");
+}
+export function extractHarborEvidenceValidationInput(body, completionPresetId) {
+    let presetId = (completionPresetId ?? "").trim();
+    if (!presetId) {
+        for (const key of ["completion_preset_id", "completion_preset"]) {
+            const raw = body[key];
+            if (typeof raw === "string" && raw.trim()) {
+                presetId = raw.trim();
+                break;
+            }
+        }
+    }
+    const vendorRaw = body.vendor_payload;
+    const vendorPayload = vendorRaw !== undefined && typeof vendorRaw === "object" && vendorRaw !== null && !Array.isArray(vendorRaw)
+        ? vendorRaw
+        : undefined;
+    const payloadRaw = body.payload;
+    const canonicalPayload = payloadRaw !== undefined && typeof payloadRaw === "object" && payloadRaw !== null && !Array.isArray(payloadRaw)
+        ? payloadRaw
+        : undefined;
+    return { presetId, vendorPayload, canonicalPayload };
+}
+export function extractSandboxGuardrailValidationInput(input) {
+    const presetId = (input.completionPresetId ?? "").trim();
+    return {
+        presetId,
+        vendorPayload: input.payload,
+        canonicalPayload: input.payload,
+    };
+}
+export class McpEvidenceValidationGate {
+    policy;
+    passes = new Set();
+    constructor(policy = DEFAULT_MCP_EVIDENCE_POLICY) {
+        this.policy = policy;
+    }
+    recordPass(gateKey) {
+        this.passes.add(gateKey);
+    }
+    hasPass(gateKey) {
+        return this.passes.has(gateKey);
+    }
+    requirePass(input) {
+        if (this.policy === "off") {
+            return;
+        }
+        const presetId = input.presetId.trim();
+        if (!presetId) {
+            return;
+        }
+        const gateKey = evidenceValidationGateKey({
+            presetId,
+            vendorPayload: input.vendorPayload,
+            canonicalPayload: input.canonicalPayload,
+        });
+        if (!this.hasPass(gateKey)) {
+            throw new McpEvidencePolicyError("completion evidence was not pre-validated; call paybond_validate_completion_evidence with the same preset and payload before submit (Harbor remains authoritative at submit time)");
+        }
+    }
+    validateAndRecord(input) {
+        const report = validateCompletionEvidence({
+            presetId: input.presetId,
+            vendorPayload: input.vendorPayload,
+            canonicalPayload: input.canonicalPayload,
+            frozenVendorApiVersion: input.frozenVendorApiVersion,
+            frozenVendorSchemaDigestHex: input.frozenVendorSchemaDigestHex,
+            frozenCanonicalSchemaDigestHex: input.frozenCanonicalSchemaDigestHex,
+        });
+        if (completionEvidenceValidationOk(report)) {
+            this.recordPass(evidenceValidationGateKey({
+                presetId: input.presetId,
+                vendorPayload: input.vendorPayload,
+                canonicalPayload: input.canonicalPayload,
+            }));
+        }
+        return report;
+    }
+}

package/dist/mcp-policy-reload.d.ts

@@ -0,0 +1,79 @@
+import { type PaybondPolicyReloadOptions, type PaybondPolicyReloadResult, type PolicyReloadHandle } from "./policy/reload.js";
+import type { PaybondPolicySnapshot } from "./policy/snapshot.js";
+import { type PolicyEffectiveResolveClient } from "./policy/load-effective.js";
+import { type PolicyRemoteValidateClient } from "./policy/validate-remote.js";
+export declare const MCP_POLICY_FILE_ENV = "PAYBOND_POLICY_FILE";
+export declare const MCP_POLICY_RELOAD_ENV = "PAYBOND_POLICY_RELOAD";
+export declare const MCP_POLICY_RELOAD_ALLOW_LOOSEN_ENV = "PAYBOND_POLICY_RELOAD_ALLOW_LOOSEN";
+export type McpPolicyReloadMode = "off" | "watch" | "poll";
+export type McpPolicyReloadConfig = {
+    policyFile: string;
+    reloadMode: McpPolicyReloadMode;
+    allowLoosen?: boolean;
+    watchDebounceMs?: number;
+    pollIntervalMs?: number;
+};
+export type McpPolicySpendGateInput = {
+    toolName?: string;
+    operation: string;
+    allowedTools: readonly string[];
+    arguments?: unknown;
+    requestedSpendCents?: number;
+};
+export type McpPolicySpendGateResult = {
+    operation: string;
+    requestedSpendCents: number;
+    policyDigest?: string;
+};
+export type McpPolicyReloadStatus = {
+    enabled: boolean;
+    policy_file?: string;
+    policy_digest?: string;
+    policy_loaded_at?: string;
+    reload_mode: McpPolicyReloadMode;
+    last_reload_at?: string;
+    last_reload_error?: string;
+};
+export declare class McpPolicyReloadError extends Error {
+    constructor(message: string);
+}
+/** Gateway adapter for MCP poll reload with remote validation. */
+export type McpPolicyGatewayClient = PolicyRemoteValidateClient & PolicyEffectiveResolveClient;
+export declare function createMcpPolicyGatewayAdapter(client: {
+    postJSON(path: string, payload: Record<string, unknown>, extraHeaders?: Record<string, string>): Promise<Record<string, unknown>>;
+}): McpPolicyGatewayClient;
+export declare function parseMcpPolicyReloadMode(raw: string | undefined): McpPolicyReloadMode;
+export declare function parseMcpPolicyReloadConfig(env: Record<string, string | undefined>): McpPolicyReloadConfig | null;
+/**
+ * Long-lived MCP policy gate: versioned snapshot, safe reload, and spend-gate registry checks.
+ */
+export declare class McpPolicyReloadGate implements PolicyReloadHandle {
+    readonly config: McpPolicyReloadConfig;
+    private _snapshot?;
+    private _inFlightCount;
+    private _lastAllowedTools;
+    private _controller?;
+    private _reloadDefaults;
+    readonly policyFilePath: string;
+    lastReloadAt?: string;
+    lastReloadError?: string;
+    private constructor();
+    static open(config: McpPolicyReloadConfig, options?: {
+        gateway?: McpPolicyGatewayClient;
+    }): Promise<McpPolicyReloadGate>;
+    get currentSnapshot(): PaybondPolicySnapshot | undefined;
+    get policyDigest(): string | undefined;
+    get inFlightCount(): number;
+    get registry(): import("./index.js").PaybondToolRegistry;
+    applyPolicySnapshot(snapshot: PaybondPolicySnapshot): void;
+    reloadPolicy(options?: PaybondPolicyReloadOptions): Promise<PaybondPolicyReloadResult>;
+    beginToolCall(): void;
+    endToolCall(): void;
+    /**
+     * Enforce paybond.policy.yaml registry rules before Harbor spend authorization.
+     * Pins policy_digest for the current MCP tool invocation.
+     */
+    assertSpendGate(input: McpPolicySpendGateInput): McpPolicySpendGateResult;
+    status(): McpPolicyReloadStatus;
+    stop(): void;
+}

package/dist/mcp-policy-reload.js

@@ -0,0 +1,200 @@
+import { resolve } from "node:path";
+import { PaybondUnregisteredSideEffectingToolError } from "./agent/types.js";
+import { loadPolicySnapshotFromFile, reloadPolicyOnHandle, } from "./policy/reload.js";
+import { parsePolicyEffectiveResolveResponse, } from "./policy/load-effective.js";
+import { parsePolicyRemoteValidateResponse, policyValidateQueryString, } from "./policy/validate-remote.js";
+import { PaybondPolicyReloadController } from "./policy/watcher.js";
+export const MCP_POLICY_FILE_ENV = "PAYBOND_POLICY_FILE";
+export const MCP_POLICY_RELOAD_ENV = "PAYBOND_POLICY_RELOAD";
+export const MCP_POLICY_RELOAD_ALLOW_LOOSEN_ENV = "PAYBOND_POLICY_RELOAD_ALLOW_LOOSEN";
+export class McpPolicyReloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpPolicyReloadError";
+    }
+}
+export function createMcpPolicyGatewayAdapter(client) {
+    return {
+        async validatePolicy(document, options) {
+            const qs = policyValidateQueryString(options ?? {});
+            const body = await client.postJSON(`/v1/policy/validate${qs}`, document);
+            return parsePolicyRemoteValidateResponse(body);
+        },
+        async resolvePolicyEffective(orgPolicyId, overlay, options) {
+            let path = `/v1/org-policies/${encodeURIComponent(orgPolicyId)}/effective`;
+            const currentDigest = options?.currentDigest?.trim();
+            if (currentDigest) {
+                path += `?digest=${encodeURIComponent(currentDigest)}`;
+            }
+            const body = await client.postJSON(path, overlay);
+            return parsePolicyEffectiveResolveResponse(body);
+        },
+    };
+}
+export function parseMcpPolicyReloadMode(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (!value || value === "off") {
+        return "off";
+    }
+    if (value === "watch" || value === "poll") {
+        return value;
+    }
+    throw new Error("invalid PAYBOND_POLICY_RELOAD (expected watch|poll|off)");
+}
+export function parseMcpPolicyReloadConfig(env) {
+    const policyFile = (env[MCP_POLICY_FILE_ENV] ?? "").trim();
+    if (!policyFile) {
+        return null;
+    }
+    return {
+        policyFile: resolve(policyFile),
+        reloadMode: parseMcpPolicyReloadMode(env[MCP_POLICY_RELOAD_ENV]),
+        allowLoosen: env[MCP_POLICY_RELOAD_ALLOW_LOOSEN_ENV] === "1",
+    };
+}
+/** MCP reload controller shim — delegates to {@link McpPolicyReloadGate}. */
+class McpPolicyReloadRunner {
+    gate;
+    constructor(gate) {
+        this.gate = gate;
+    }
+    reloadPolicy(options) {
+        return this.gate.reloadPolicy(options);
+    }
+}
+/**
+ * Long-lived MCP policy gate: versioned snapshot, safe reload, and spend-gate registry checks.
+ */
+export class McpPolicyReloadGate {
+    config;
+    _snapshot;
+    _inFlightCount = 0;
+    _lastAllowedTools = [];
+    _controller;
+    _reloadDefaults = {};
+    policyFilePath;
+    lastReloadAt;
+    lastReloadError;
+    constructor(config, snapshot) {
+        this.config = config;
+        this.policyFilePath = config.policyFile;
+        this._snapshot = snapshot;
+    }
+    static async open(config, options) {
+        const snapshot = await loadPolicySnapshotFromFile(config.policyFile);
+        const gate = new McpPolicyReloadGate(config, snapshot);
+        const runner = new McpPolicyReloadRunner(gate);
+        gate._reloadDefaults = {
+            file: config.policyFile,
+            allowLoosen: config.allowLoosen,
+            gateway: options?.gateway,
+        };
+        if (config.reloadMode === "watch") {
+            gate._controller = PaybondPolicyReloadController.start(runner, { watch: { debounceMs: config.watchDebounceMs } }, config.policyFile);
+        }
+        else if (config.reloadMode === "poll") {
+            gate._reloadDefaults.remote = true;
+            gate._reloadDefaults.resolveInheritance = true;
+            gate._controller = PaybondPolicyReloadController.start(runner, {
+                poll: {
+                    intervalMs: config.pollIntervalMs,
+                    remote: true,
+                    resolveInheritance: true,
+                    gateway: options?.gateway,
+                },
+            }, config.policyFile);
+        }
+        return gate;
+    }
+    get currentSnapshot() {
+        return this._snapshot;
+    }
+    get policyDigest() {
+        return this._snapshot?.digest;
+    }
+    get inFlightCount() {
+        return this._inFlightCount;
+    }
+    get registry() {
+        const snapshot = this._snapshot;
+        if (!snapshot) {
+            throw new McpPolicyReloadError("policy snapshot is not loaded");
+        }
+        return snapshot.registry;
+    }
+    applyPolicySnapshot(snapshot) {
+        this._snapshot = snapshot;
+    }
+    async reloadPolicy(options = {}) {
+        try {
+            const result = await reloadPolicyOnHandle(this, {
+                ...this._reloadDefaults,
+                ...options,
+                allowedTools: this._lastAllowedTools,
+            });
+            if (result.applied) {
+                this.lastReloadAt = new Date().toISOString();
+                this.lastReloadError = undefined;
+            }
+            return result;
+        }
+        catch (err) {
+            this.lastReloadError = err instanceof Error ? err.message : String(err);
+            throw err;
+        }
+    }
+    beginToolCall() {
+        this._inFlightCount += 1;
+    }
+    endToolCall() {
+        this._inFlightCount = Math.max(0, this._inFlightCount - 1);
+    }
+    /**
+     * Enforce paybond.policy.yaml registry rules before Harbor spend authorization.
+     * Pins policy_digest for the current MCP tool invocation.
+     */
+    assertSpendGate(input) {
+        const operation = input.operation.trim();
+        const toolName = (input.toolName ?? operation).trim();
+        if (!operation) {
+            throw new McpPolicyReloadError("operation must be non-empty");
+        }
+        this._lastAllowedTools = input.allowedTools;
+        const policyDigest = this._snapshot?.digest;
+        const resolution = this.registry.resolveTool(toolName, {
+            allowedTools: input.allowedTools,
+        });
+        if (resolution.kind === "passthrough") {
+            return { operation, requestedSpendCents: 0, policyDigest };
+        }
+        if (resolution.kind === "denied") {
+            throw new PaybondUnregisteredSideEffectingToolError(resolution.toolName, resolution.operation);
+        }
+        if (!input.allowedTools.includes(operation)) {
+            throw new McpPolicyReloadError(`operation "${operation}" is not in intent allowed_tools (${input.allowedTools.join(", ")})`);
+        }
+        const requestedSpendCents = input.requestedSpendCents ??
+            this.registry.resolveSpendCents(toolName, input.arguments) ??
+            0;
+        return {
+            operation: resolution.operation,
+            requestedSpendCents,
+            policyDigest,
+        };
+    }
+    status() {
+        return {
+            enabled: true,
+            policy_file: this.policyFilePath,
+            policy_digest: this.policyDigest,
+            policy_loaded_at: this._snapshot?.loadedAt,
+            reload_mode: this.config.reloadMode,
+            last_reload_at: this.lastReloadAt ?? this._controller?.state.lastReloadAt,
+            last_reload_error: this.lastReloadError ?? this._controller?.state.lastReloadError,
+        };
+    }
+    stop() {
+        this._controller?.stop();
+        this._controller = undefined;
+    }
+}

package/dist/mcp-sep2828-evidence.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Maps SEP-2828-style MCP decision/outcome execution records into artifact_attested evidence.
+ *
+ * Wire shapes follow the draft SEP-2828 pairing model: decision record (pre-side-effect) and
+ * outcome record (post-execution) linked via backLink and outcomeDerived.decisionDigest.
+ */
+export type Sep2828BackLink = {
+    attestationDigest: string;
+    attestationNonce?: string;
+};
+export type Sep2828DecisionRecord = {
+    backLink?: Sep2828BackLink;
+    decisionDerived?: {
+        decision?: "allow" | "block" | "escalate";
+    };
+};
+export type Sep2828OutcomeRecord = {
+    backLink?: Sep2828BackLink;
+    outcomeDerived?: {
+        status?: "executed" | "refused" | "errored";
+        decisionDigest?: string;
+        resultCommitment?: string;
+        completedAt?: string;
+    };
+};
+export type ArtifactAttestedEvidence = {
+    artifact_blake3_hex: string[];
+    operation: string;
+    vendor_ref_id: string;
+};
+/** Strips sha256:/blake3: prefixes so digests fit artifact_blake3_hex entries. */
+export declare function stripDigestPrefix(digest: string): string;
+/**
+ * Converts paired SEP-2828 decision and outcome records into artifact_attested evidence fields.
+ */
+export declare function mapSep2828ReceiptsToArtifactAttestedEvidence(decisionInput: Record<string, unknown>, outcomeInput: Record<string, unknown>): ArtifactAttestedEvidence;