@paybond/kit 0.9.8 → 0.11.0

package/dist/policy/reload.d.ts

@@ -0,0 +1,86 @@
+import type { PaybondAgentRun } from "../agent/run.js";
+import { type PaybondPolicyDocumentV1 } from "./schema.js";
+import { type PaybondPolicySnapshot } from "./snapshot.js";
+import { type PolicyRemoteValidateClient } from "./validate-remote.js";
+import type { PolicyEffectiveResolveClient } from "./load-effective.js";
+/** Options for {@link PaybondAgentRun.reloadPolicy}. */
+export type PaybondPolicyReloadOptions = {
+    /** Policy file path; defaults to the path used at bind when omitted. */
+    file?: string;
+    /** Run Gateway `POST /v1/policy/validate` before applying (recommended in production). */
+    remote?: boolean;
+    /** Resolve org inheritance via Gateway effective endpoint before validate. */
+    resolveInheritance?: boolean;
+    /** Allow policy loosening (higher caps, new side-effecting tools). Default deny. */
+    allowLoosen?: boolean;
+    /** Gateway client for remote validate / effective resolution. */
+    gateway?: PolicyRemoteValidateClient & PolicyEffectiveResolveClient;
+};
+export type PaybondPolicyReloadResult = {
+    applied: boolean;
+    previousDigest?: string;
+    newDigest?: string;
+    unchanged?: boolean;
+};
+export type PaybondPolicyReloadFailedEvent = {
+    error: PaybondPolicyReloadError;
+};
+export type PaybondPolicyReloadedEvent = {
+    previousDigest: string;
+    newDigest: string;
+};
+/** Structured reload failure (parse, validate, loosening, intent drift). */
+export declare class PaybondPolicyReloadError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Thrown internally when poll/file reload finds an unchanged digest. */
+export declare class PaybondPolicyReloadUnchangedError extends Error {
+    constructor();
+}
+export type PaybondPolicyReloadBindConfig = {
+    /** Watch the bound policy file and reload on change. */
+    watch?: boolean | {
+        debounceMs?: number;
+        file?: string;
+    };
+    /** Poll Gateway for effective inherited policy changes. */
+    poll?: {
+        intervalMs?: number;
+        file?: string;
+        remote?: boolean;
+        resolveInheritance?: boolean;
+        gateway?: PolicyRemoteValidateClient & PolicyEffectiveResolveClient;
+    };
+};
+/** Load a versioned snapshot from a policy file path. */
+export declare function loadPolicySnapshotFromFile(filePath: string): Promise<PaybondPolicySnapshot>;
+/** Poll Gateway effective resolution; returns unchanged when digest matches. */
+export declare function loadPolicySnapshotFromEffectivePoll(options: {
+    overlayPath: string;
+    gateway: PolicyEffectiveResolveClient;
+    currentDigest?: string;
+}): Promise<{
+    snapshot?: PaybondPolicySnapshot;
+    unchanged: boolean;
+}>;
+/** Detect policy loosening between two effective documents. */
+export declare function detectPolicyLoosening(previous: PaybondPolicyDocumentV1, next: PaybondPolicyDocumentV1): string[];
+/** True when reloaded policy requires operations outside the bound intent. */
+export declare function requiresIntentRebind(document: PaybondPolicyDocumentV1, allowedTools: readonly string[]): boolean;
+/** Mutable policy reload surface shared by agent runs and MCP servers. */
+export type PolicyReloadHandle = {
+    readonly policyFilePath?: string;
+    readonly policyDigest?: string;
+    readonly currentSnapshot?: PaybondPolicySnapshot;
+    readonly inFlightCount: number;
+    applyPolicySnapshot(snapshot: PaybondPolicySnapshot): void;
+};
+/** Reload policy for any {@link PolicyReloadHandle} (agent run or MCP gate). */
+export declare function reloadPolicyOnHandle(handle: PolicyReloadHandle, options?: PaybondPolicyReloadOptions & {
+    allowedTools?: readonly string[];
+}): Promise<PaybondPolicyReloadResult>;
+/** Apply a validated snapshot to a run (atomic registry swap). */
+export declare function applyPolicySnapshotToRun(run: PaybondAgentRun, snapshot: PaybondPolicySnapshot): PaybondPolicyReloadResult;
+/** Core reload pipeline: load, validate, guard, swap. */
+export declare function reloadPolicyOnRun(run: PaybondAgentRun, options?: PaybondPolicyReloadOptions): Promise<PaybondPolicyReloadResult>;

package/dist/policy/reload.js

@@ -0,0 +1,233 @@
+import { readFile } from "node:fs/promises";
+import { PaybondPolicy } from "./load.js";
+import { parsePolicyDocumentText } from "./parse-text.js";
+import { isPaybondPolicyDocumentV2, isPaybondPolicyOverlay, parsePaybondPolicyDocument, parsePaybondPolicyDocumentV1, } from "./schema.js";
+import { createPolicySnapshot, createPolicySnapshotFromEffective, } from "./snapshot.js";
+import { PolicyValidator } from "./validate.js";
+import { validatePolicyRemote, } from "./validate-remote.js";
+/** Structured reload failure (parse, validate, loosening, intent drift). */
+export class PaybondPolicyReloadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PaybondPolicyReloadError";
+        this.code = code;
+    }
+}
+/** Thrown internally when poll/file reload finds an unchanged digest. */
+export class PaybondPolicyReloadUnchangedError extends Error {
+    constructor() {
+        super("policy digest unchanged");
+        this.name = "PaybondPolicyReloadUnchangedError";
+    }
+}
+/** Load a versioned snapshot from a policy file path. */
+export async function loadPolicySnapshotFromFile(filePath) {
+    const policy = await PaybondPolicy.load(filePath);
+    const registry = policy.toToolRegistry();
+    return createPolicySnapshot({
+        document: policy.document,
+        registry,
+        source: "file",
+    });
+}
+/** Poll Gateway effective resolution; returns unchanged when digest matches. */
+export async function loadPolicySnapshotFromEffectivePoll(options) {
+    const text = await readFile(options.overlayPath, "utf8");
+    const overlayDoc = parsePaybondPolicyDocument(parsePolicyDocumentText(text));
+    if (!isPaybondPolicyDocumentV2(overlayDoc) || !isPaybondPolicyOverlay(overlayDoc)) {
+        throw new PaybondPolicyReloadError("invalid_overlay", "poll reload requires a v2 tenant overlay policy with extends.org_policy_id");
+    }
+    const orgPolicyId = overlayDoc.extends?.org_policy_id?.trim();
+    if (!orgPolicyId) {
+        throw new PaybondPolicyReloadError("invalid_overlay", "poll reload requires extends.org_policy_id on the overlay policy");
+    }
+    const resolved = await options.gateway.resolvePolicyEffective(orgPolicyId, overlayDoc, { currentDigest: options.currentDigest });
+    if (resolved.unchanged) {
+        return { unchanged: true };
+    }
+    const effective = parsePaybondPolicyDocumentV1(resolved.effective_policy);
+    const policy = PaybondPolicy.fromDocument(effective);
+    const registry = policy.toToolRegistry();
+    const snapshot = createPolicySnapshotFromEffective({
+        document: effective,
+        registry,
+        effectivePolicyDigest: resolved.effective_policy_digest,
+    });
+    return { snapshot, unchanged: false };
+}
+function readMaxSpendCents(entry) {
+    return typeof entry.max_spend_cents === "number" ? entry.max_spend_cents : undefined;
+}
+/** Detect policy loosening between two effective documents. */
+export function detectPolicyLoosening(previous, next) {
+    const reasons = [];
+    if (previous.default_deny && !next.default_deny) {
+        reasons.push("default_deny relaxed from true to false");
+    }
+    for (const [toolName, nextEntry] of Object.entries(next.tools)) {
+        const prevEntry = previous.tools[toolName];
+        if (!prevEntry) {
+            if (nextEntry.side_effecting) {
+                reasons.push(`new side-effecting tool "${toolName}"`);
+            }
+            continue;
+        }
+        const prevCap = readMaxSpendCents(prevEntry);
+        const nextCap = readMaxSpendCents(nextEntry);
+        if (prevCap !== undefined) {
+            if (nextCap === undefined) {
+                reasons.push(`tool "${toolName}" max_spend_cents cap removed`);
+            }
+            else if (nextCap > prevCap) {
+                reasons.push(`tool "${toolName}" max_spend_cents increased from ${prevCap} to ${nextCap}`);
+            }
+        }
+        if (!prevEntry.side_effecting && nextEntry.side_effecting) {
+            reasons.push(`tool "${toolName}" became side-effecting`);
+        }
+    }
+    return reasons;
+}
+/** True when reloaded policy requires operations outside the bound intent. */
+export function requiresIntentRebind(document, allowedTools) {
+    const intentTools = document.intent?.allowed_tools ?? [];
+    for (const operation of intentTools) {
+        if (!allowedTools.includes(operation)) {
+            return true;
+        }
+    }
+    for (const [toolName, entry] of Object.entries(document.tools)) {
+        if (!entry.side_effecting) {
+            continue;
+        }
+        const operation = entry.operation?.trim() || toolName;
+        if (!allowedTools.includes(operation)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function waitForInFlightInterceptors(interceptor, timeoutMs = 30_000) {
+    await waitForInFlightCount(() => interceptor.inFlightCount, timeoutMs);
+}
+async function waitForInFlightCount(readCount, timeoutMs = 30_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (readCount() > 0) {
+        if (Date.now() > deadline) {
+            throw new PaybondPolicyReloadError("in_flight_timeout", "timed out waiting for in-flight tool calls before policy reload");
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+}
+async function resolveReloadSnapshotForHandle(handle, options) {
+    const filePath = options.file?.trim() || handle.policyFilePath;
+    if (!filePath) {
+        throw new PaybondPolicyReloadError("missing_policy_file", "reload requires a policy file path (pass file or bind with reload.watch/poll)");
+    }
+    if (options.resolveInheritance && options.gateway) {
+        const polled = await loadPolicySnapshotFromEffectivePoll({
+            overlayPath: filePath,
+            gateway: options.gateway,
+            currentDigest: handle.policyDigest,
+        });
+        if (polled.unchanged) {
+            throw new PaybondPolicyReloadUnchangedError();
+        }
+        if (!polled.snapshot) {
+            throw new PaybondPolicyReloadError("effective_empty", "effective policy resolution returned no snapshot");
+        }
+        return polled.snapshot;
+    }
+    const snapshot = await loadPolicySnapshotFromFile(filePath);
+    if (handle.policyDigest && handle.policyDigest === snapshot.digest) {
+        throw new PaybondPolicyReloadUnchangedError();
+    }
+    return snapshot;
+}
+async function validateAndApplyPolicySnapshot(handle, snapshot, options, allowedTools) {
+    const previousDocument = handle.currentSnapshot?.document;
+    const nextDocument = snapshot.document;
+    const localReport = await PolicyValidator.validateDocument(nextDocument, {
+        strict: PolicyValidator.isStrictFromEnv(),
+    });
+    if (!localReport.valid) {
+        const first = localReport.errors[0];
+        throw new PaybondPolicyReloadError("local_validate_failed", first ? `${first.path}: ${first.message}` : "local policy validation failed");
+    }
+    if (options.remote && options.gateway) {
+        const remoteReport = await validatePolicyRemote(nextDocument, options.gateway, {
+            resolveInheritance: options.resolveInheritance,
+            strict: PolicyValidator.isStrictFromEnv(),
+        });
+        if (!remoteReport.valid) {
+            const first = remoteReport.errors[0];
+            throw new PaybondPolicyReloadError("remote_validate_failed", first ? `${first.path}: ${first.message}` : "remote policy validation failed");
+        }
+    }
+    if (allowedTools.length > 0 && requiresIntentRebind(nextDocument, allowedTools)) {
+        throw new PaybondPolicyReloadError("intent_rebind_required", "reloaded policy requires allowed_tools outside the bound intent; re-bind with a new intent");
+    }
+    if (previousDocument && !options.allowLoosen) {
+        const loosening = detectPolicyLoosening(previousDocument, nextDocument);
+        if (loosening.length > 0) {
+            throw new PaybondPolicyReloadError("loosening_denied", `policy loosening denied: ${loosening.join("; ")}`);
+        }
+    }
+    if (allowedTools.length > 0) {
+        snapshot.registry.validateForBind(allowedTools);
+    }
+    const previousDigest = handle.policyDigest;
+    if (previousDigest && previousDigest === snapshot.digest) {
+        return { applied: false, previousDigest, newDigest: snapshot.digest, unchanged: true };
+    }
+    handle.applyPolicySnapshot(snapshot);
+    return {
+        applied: true,
+        previousDigest: previousDigest ?? snapshot.digest,
+        newDigest: snapshot.digest,
+    };
+}
+/** Reload policy for any {@link PolicyReloadHandle} (agent run or MCP gate). */
+export async function reloadPolicyOnHandle(handle, options = {}) {
+    await waitForInFlightCount(() => handle.inFlightCount);
+    let snapshot;
+    try {
+        snapshot = await resolveReloadSnapshotForHandle(handle, options);
+    }
+    catch (err) {
+        if (err instanceof PaybondPolicyReloadUnchangedError) {
+            return {
+                applied: false,
+                previousDigest: handle.policyDigest,
+                newDigest: handle.policyDigest,
+                unchanged: true,
+            };
+        }
+        throw err;
+    }
+    const allowedTools = options.allowedTools ??
+        handle.currentSnapshot?.document.intent?.allowed_tools ??
+        [];
+    return validateAndApplyPolicySnapshot(handle, snapshot, options, allowedTools);
+}
+/** Apply a validated snapshot to a run (atomic registry swap). */
+export function applyPolicySnapshotToRun(run, snapshot) {
+    const previousDigest = run.policyDigest;
+    if (previousDigest && previousDigest === snapshot.digest) {
+        return { applied: false, previousDigest, newDigest: snapshot.digest, unchanged: true };
+    }
+    run.applyPolicySnapshot(snapshot);
+    return {
+        applied: true,
+        previousDigest: previousDigest ?? snapshot.digest,
+        newDigest: snapshot.digest,
+    };
+}
+/** Core reload pipeline: load, validate, guard, swap. */
+export async function reloadPolicyOnRun(run, options = {}) {
+    return reloadPolicyOnHandle(run, {
+        ...options,
+        allowedTools: run.allowedTools,
+    });
+}

package/dist/policy/render-yaml.d.ts

@@ -0,0 +1,3 @@
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+/** Serialize a validated v1 policy document to paybond.policy.yaml text. */
+export declare function renderPolicyDocumentYaml(document: PaybondPolicyDocumentV1): string;

package/dist/policy/render-yaml.js

@@ -0,0 +1,69 @@
+function yamlScalar(value) {
+    if (/^[a-z0-9_.-]+$/i.test(value)) {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+function renderToolEntry(entry, indent) {
+    const lines = [`${indent}side_effecting: ${entry.side_effecting}`];
+    if (entry.max_spend_cents !== undefined) {
+        lines.push(`${indent}max_spend_cents: ${entry.max_spend_cents}`);
+    }
+    if (entry.spend_from_args !== undefined) {
+        lines.push(`${indent}spend_from_args: ${yamlScalar(entry.spend_from_args)}`);
+    }
+    if (entry.evidence_preset !== undefined) {
+        lines.push(`${indent}evidence_preset: ${entry.evidence_preset}`);
+    }
+    if (entry.vendor_pack !== undefined) {
+        lines.push(`${indent}vendor_pack: ${entry.vendor_pack}`);
+    }
+    if (entry.operation !== undefined) {
+        lines.push(`${indent}operation: ${yamlScalar(entry.operation)}`);
+    }
+    return lines;
+}
+/** Serialize a validated v1 policy document to paybond.policy.yaml text. */
+export function renderPolicyDocumentYaml(document) {
+    const lines = [
+        `version: ${document.version}`,
+        `name: ${document.name}`,
+        `default_deny: ${document.default_deny}`,
+        "",
+        "tools:",
+    ];
+    for (const [toolName, entry] of Object.entries(document.tools)) {
+        lines.push(`  ${toolName}:`);
+        lines.push(...renderToolEntry(entry, "    "));
+        lines.push("");
+    }
+    if (document.intent) {
+        lines.push("intent:");
+        if (document.intent.allowed_tools?.length) {
+            lines.push("  allowed_tools:");
+            for (const tool of document.intent.allowed_tools) {
+                lines.push(`    - ${tool}`);
+            }
+        }
+        if (document.intent.budget) {
+            lines.push("  budget:");
+            if (document.intent.budget.currency) {
+                lines.push(`    currency: ${document.intent.budget.currency}`);
+            }
+            if (document.intent.budget.max_spend_usd !== undefined) {
+                lines.push(`    max_spend_usd: ${document.intent.budget.max_spend_usd}`);
+            }
+        }
+        if (document.intent.policy_binding) {
+            lines.push("  policy_binding:");
+            lines.push(`    template_id: ${document.intent.policy_binding.template_id}`);
+            if (document.intent.policy_binding.version_seq !== undefined) {
+                lines.push(`    version_seq: ${document.intent.policy_binding.version_seq}`);
+            }
+            if (document.intent.policy_binding.head_digest !== undefined) {
+                lines.push(`    head_digest: ${document.intent.policy_binding.head_digest}`);
+            }
+        }
+    }
+    return `${lines.join("\n").replace(/\n+$/u, "")}\n`;
+}

package/dist/policy/sandbox-bootstrap.d.ts

@@ -0,0 +1,19 @@
+import type { PaybondRunBindingSandboxBootstrapInput } from "../agent/types.js";
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+/** Raised when policy cannot derive sandbox bootstrap parameters. */
+export declare class PaybondPolicySandboxBootstrapError extends Error {
+    constructor(message: string);
+}
+export type PaybondPolicySandboxBootstrapOptions = {
+    /** Registry tool name to bootstrap against. */
+    toolName?: string;
+    /** Harbor operation string; matched against tool names and optional `operation` overrides. */
+    operation?: string;
+    requestedSpendCents?: number;
+    currency?: string;
+    evidenceSchema?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+};
+/** Build {@link PaybondAgentRun.bind} sandbox bootstrap input from a validated policy document. */
+export declare function policySandboxBootstrap(document: PaybondPolicyDocumentV1, options?: PaybondPolicySandboxBootstrapOptions): PaybondRunBindingSandboxBootstrapInput;

package/dist/policy/sandbox-bootstrap.js

@@ -0,0 +1,66 @@
+import { getCompletionPreset } from "../completion-catalog.js";
+/** Raised when policy cannot derive sandbox bootstrap parameters. */
+export class PaybondPolicySandboxBootstrapError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PaybondPolicySandboxBootstrapError";
+    }
+}
+function listSideEffectingTools(document) {
+    return Object.entries(document.tools).filter(([, entry]) => entry.side_effecting);
+}
+function resolveHarborOperation(toolName, entry) {
+    return entry.operation?.trim() || toolName;
+}
+function resolveSideEffectingTool(document, options) {
+    const sideEffecting = listSideEffectingTools(document);
+    if (sideEffecting.length === 0) {
+        throw new PaybondPolicySandboxBootstrapError("policy has no side-effecting tools for sandbox bootstrap");
+    }
+    if (options.toolName?.trim()) {
+        const toolName = options.toolName.trim();
+        const entry = document.tools[toolName];
+        if (!entry?.side_effecting) {
+            throw new PaybondPolicySandboxBootstrapError(`tool "${toolName}" is not a registered side-effecting tool in policy`);
+        }
+        return { toolName, entry };
+    }
+    if (options.operation?.trim()) {
+        const operation = options.operation.trim();
+        for (const [toolName, entry] of sideEffecting) {
+            const harborOperation = resolveHarborOperation(toolName, entry);
+            if (harborOperation === operation || toolName === operation) {
+                return { toolName, entry };
+            }
+        }
+        throw new PaybondPolicySandboxBootstrapError(`operation "${operation}" does not match any side-effecting tool in policy`);
+    }
+    const [toolName, entry] = sideEffecting[0];
+    return { toolName, entry };
+}
+/** Build {@link PaybondAgentRun.bind} sandbox bootstrap input from a validated policy document. */
+export function policySandboxBootstrap(document, options = {}) {
+    const { toolName, entry } = resolveSideEffectingTool(document, options);
+    const operation = resolveHarborOperation(toolName, entry);
+    const evidencePreset = entry.evidence_preset;
+    const preset = getCompletionPreset(evidencePreset);
+    let requestedSpendCents = options.requestedSpendCents;
+    if (requestedSpendCents === undefined) {
+        requestedSpendCents = entry.max_spend_cents ?? preset.recommended_amount_cents ?? 0;
+    }
+    if (!Number.isFinite(requestedSpendCents) || requestedSpendCents < 0) {
+        throw new PaybondPolicySandboxBootstrapError("requestedSpendCents must be a non-negative number");
+    }
+    return {
+        kind: "sandbox",
+        operation,
+        requestedSpendCents,
+        currency: options.currency ?? document.intent?.budget?.currency,
+        evidenceSchema: options.evidenceSchema ?? preset.evidence_schema,
+        completionPreset: evidencePreset,
+        metadata: options.metadata,
+        idempotencyKey: options.idempotencyKey,
+        templateId: preset.harbor_template_id,
+        parameters: preset.parameters,
+    };
+}