@paybond/kit 0.10.0 → 0.11.0

package/dist/agent/registry-file.js

@@ -0,0 +1,219 @@
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { getCompletionPreset, listCompletionPresetIds } from "../completion-catalog.js";
+import { createPaybondToolRegistry } from "./registry.js";
+import { PaybondToolRegistryValidationError, } from "./types.js";
+function isSideEffecting(entry) {
+    const raw = entry.side_effecting ?? entry.sideEffecting;
+    return raw !== false;
+}
+function evidencePreset(entry) {
+    const raw = entry.evidence_preset ?? entry.evidencePreset;
+    return typeof raw === "string" && raw.trim() ? raw.trim() : undefined;
+}
+function normalizeDocument(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new PaybondToolRegistryValidationError("registry file must be a JSON or YAML object");
+    }
+    return raw;
+}
+/** Parse registry file text (JSON or YAML). */
+export function parseAgentRegistryText(text, sourceLabel = "registry file") {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        throw new PaybondToolRegistryValidationError(`${sourceLabel} is empty`);
+    }
+    try {
+        return normalizeDocument(JSON.parse(trimmed));
+    }
+    catch {
+        return normalizeDocument(parseSimpleYamlRegistry(trimmed, sourceLabel));
+    }
+}
+/** Load and parse a registry file from disk. */
+export async function loadAgentRegistryFile(path) {
+    const text = await readFile(path, "utf8");
+    return parseAgentRegistryText(text, path);
+}
+function parseSimpleYamlRegistry(text, sourceLabel) {
+    const ext = extname(sourceLabel).toLowerCase();
+    if (ext !== ".yaml" && ext !== ".yml" && !text.includes("\n") && !text.includes(":")) {
+        throw new PaybondToolRegistryValidationError(`${sourceLabel} is not valid JSON`);
+    }
+    const root = {};
+    let section = "root";
+    let currentTool = null;
+    const tools = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const match = /^(\S+?):\s*(.*)$/.exec(line);
+        if (!match) {
+            throw new PaybondToolRegistryValidationError(`${sourceLabel} has invalid YAML line: ${rawLine}`);
+        }
+        const [, key, rawValue] = match;
+        const value = rawValue.trim();
+        if (section === "root" && key === "tools" && !value) {
+            section = "tools";
+            continue;
+        }
+        if (section === "tools" && !value) {
+            currentTool = key;
+            tools[currentTool] = {};
+            continue;
+        }
+        const parsedValue = parseYamlScalar(value);
+        if (section === "tools" && currentTool) {
+            tools[currentTool][key] = parsedValue;
+            continue;
+        }
+        root[key] = parsedValue;
+    }
+    if (Object.keys(tools).length > 0) {
+        root.tools = tools;
+    }
+    return root;
+}
+function parseYamlScalar(value) {
+    if (!value) {
+        return "";
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    if (/^-?\d+$/.test(value)) {
+        return Number.parseInt(value, 10);
+    }
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/** Convert a registry file document into middleware registry config. */
+export function agentRegistryDocumentToConfig(doc) {
+    const defaultDeny = Boolean(doc.default_deny ?? doc.defaultDeny ?? false);
+    const sideEffecting = {};
+    for (const [toolName, entry] of Object.entries(doc.tools ?? {})) {
+        if (!entry || typeof entry !== "object") {
+            continue;
+        }
+        if (!isSideEffecting(entry)) {
+            continue;
+        }
+        const preset = evidencePreset(entry);
+        if (!preset) {
+            throw new PaybondToolRegistryValidationError(`side-effecting tool "${toolName}" must declare evidence_preset`);
+        }
+        const policy = {
+            evidencePreset: preset,
+        };
+        if (entry.operation?.trim()) {
+            policy.operation = entry.operation.trim();
+        }
+        sideEffecting[toolName] = policy;
+    }
+    return { defaultDeny, sideEffecting };
+}
+/** Validate registry document semantics before bind or smoke tests. */
+export function validateAgentRegistryDocument(doc) {
+    const issues = [];
+    const version = typeof doc.version === "number" ? doc.version : null;
+    if (version !== null && version !== 1) {
+        issues.push({
+            code: "registry.unsupported_version",
+            message: `unsupported registry version ${version}; expected 1`,
+        });
+    }
+    const defaultDeny = Boolean(doc.default_deny ?? doc.defaultDeny ?? false);
+    if (defaultDeny) {
+        issues.push({
+            code: "registry.default_deny_documented",
+            message: "default_deny is enabled: every intent allowed operation must be registered as side-effecting",
+        });
+    }
+    const tools = doc.tools ?? {};
+    const operations = new Map();
+    let sideEffectingCount = 0;
+    for (const [toolName, entry] of Object.entries(tools)) {
+        if (!entry || typeof entry !== "object") {
+            issues.push({
+                code: "registry.invalid_tool_entry",
+                message: `tool "${toolName}" must be an object`,
+                tool: toolName,
+            });
+            continue;
+        }
+        if (!isSideEffecting(entry)) {
+            continue;
+        }
+        sideEffectingCount += 1;
+        const preset = evidencePreset(entry);
+        if (!preset) {
+            issues.push({
+                code: "registry.missing_evidence_preset",
+                message: `side-effecting tool "${toolName}" must declare evidence_preset`,
+                tool: toolName,
+            });
+            continue;
+        }
+        try {
+            getCompletionPreset(preset);
+        }
+        catch {
+            issues.push({
+                code: "registry.unknown_evidence_preset",
+                message: `tool "${toolName}" references unknown evidence_preset "${preset}" (catalog: ${listCompletionPresetIds().join(", ")})`,
+                tool: toolName,
+            });
+        }
+        const operation = (entry.operation?.trim() || toolName).trim();
+        const previous = operations.get(operation);
+        if (previous !== undefined && previous !== toolName) {
+            issues.push({
+                code: "registry.duplicate_operation",
+                message: `duplicate operation "${operation}" for tools "${previous}" and "${toolName}"`,
+                tool: toolName,
+            });
+        }
+        else {
+            operations.set(operation, toolName);
+        }
+    }
+    let registry;
+    if (issues.every((issue) => issue.code === "registry.default_deny_documented")) {
+        try {
+            registry = createPaybondToolRegistry(agentRegistryDocumentToConfig(doc));
+        }
+        catch (err) {
+            issues.push({
+                code: "registry.invalid_config",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const blocking = issues.filter((issue) => issue.code !== "registry.default_deny_documented");
+    return {
+        ok: blocking.length === 0,
+        version,
+        default_deny: defaultDeny,
+        tool_count: Object.keys(tools).length,
+        side_effecting_count: sideEffectingCount,
+        issues,
+        registry,
+    };
+}
+/** Build a single-tool registry for sandbox smoke when no registry file is supplied. */
+export function buildSmokeRegistry(operation, evidencePresetId) {
+    return createPaybondToolRegistry({
+        defaultDeny: true,
+        sideEffecting: {
+            [operation]: { evidencePreset: evidencePresetId, operation },
+        },
+    });
+}

package/dist/agent/registry.d.ts

@@ -0,0 +1,37 @@
+import { PaybondSideEffectingToolEntry, PaybondToolRegistryConfig, PaybondToolResolution } from "./types.js";
+/**
+ * Registry of side-effecting tools for agent middleware.
+ * Read-only tools pass through without Harbor verify or evidence submission.
+ */
+export declare class PaybondToolRegistry {
+    readonly defaultDeny: boolean;
+    private readonly sideEffecting;
+    private readonly operations;
+    constructor(config: PaybondToolRegistryConfig);
+    /** Whether the tool is explicitly registered as side-effecting. */
+    isSideEffecting(toolName: string): boolean;
+    /** Resolve Harbor operation for a tool name (defaults to tool name). */
+    resolveOperation(toolName: string): string;
+    /** Resolve requested spend cents for a registered side-effecting tool. */
+    resolveSpendCents(toolName: string, args: unknown): number | undefined;
+    /** Lookup side-effecting entry by tool name. */
+    getSideEffectingEntry(toolName: string): PaybondSideEffectingToolEntry | undefined;
+    /** Registered side-effecting tool names. */
+    sideEffectingToolNames(): string[];
+    /** Registered Harbor operations for side-effecting tools. */
+    sideEffectingOperations(): string[];
+    /**
+     * Classify a tool call for interceptor routing.
+     * When `defaultDeny` is true, unregistered tools whose operation is in `allowedTools` are denied.
+     */
+    resolveTool(toolName: string, options?: {
+        allowedTools?: readonly string[];
+    }): PaybondToolResolution;
+    /**
+     * Bind-time validation: when `defaultDeny` is enabled, every intent allowed operation
+     * must have a registered side-effecting tool entry.
+     */
+    validateForBind(allowedTools: readonly string[]): void;
+}
+/** Create a validated tool registry for agent middleware. */
+export declare function createPaybondToolRegistry(config: PaybondToolRegistryConfig): PaybondToolRegistry;

package/dist/agent/registry.js

@@ -0,0 +1,128 @@
+import { getCompletionPreset } from "../completion-catalog.js";
+import { PaybondToolRegistryValidationError, } from "./types.js";
+function normalizeSideEffecting(sideEffecting) {
+    const entries = new Map();
+    const operations = new Map();
+    for (const [toolName, policy] of Object.entries(sideEffecting)) {
+        if (!toolName.trim()) {
+            throw new PaybondToolRegistryValidationError("side-effecting tool name must be non-empty");
+        }
+        const evidencePreset = policy.evidencePreset?.trim();
+        if (!evidencePreset) {
+            throw new PaybondToolRegistryValidationError(`side-effecting tool "${toolName}" must declare evidencePreset`);
+        }
+        try {
+            getCompletionPreset(evidencePreset);
+        }
+        catch {
+            throw new PaybondToolRegistryValidationError(`side-effecting tool "${toolName}" references unknown evidencePreset "${evidencePreset}"`);
+        }
+        const operation = (policy.operation?.trim() || toolName).trim();
+        if (!operation) {
+            throw new PaybondToolRegistryValidationError(`side-effecting tool "${toolName}" must resolve to a non-empty operation`);
+        }
+        const previousTool = operations.get(operation);
+        if (previousTool !== undefined && previousTool !== toolName) {
+            throw new PaybondToolRegistryValidationError(`duplicate side-effecting operation "${operation}" for tools "${previousTool}" and "${toolName}"`);
+        }
+        operations.set(operation, toolName);
+        entries.set(toolName, {
+            toolName,
+            operation,
+            spendCents: policy.spendCents,
+            evidencePreset,
+            evidenceMapper: policy.evidenceMapper,
+        });
+    }
+    return entries;
+}
+/**
+ * Registry of side-effecting tools for agent middleware.
+ * Read-only tools pass through without Harbor verify or evidence submission.
+ */
+export class PaybondToolRegistry {
+    defaultDeny;
+    sideEffecting;
+    operations;
+    constructor(config) {
+        this.defaultDeny = config.defaultDeny ?? false;
+        this.sideEffecting = normalizeSideEffecting(config.sideEffecting ?? {});
+        this.operations = new Set([...this.sideEffecting.values()].map((entry) => entry.operation));
+    }
+    /** Whether the tool is explicitly registered as side-effecting. */
+    isSideEffecting(toolName) {
+        return this.sideEffecting.has(toolName);
+    }
+    /** Resolve Harbor operation for a tool name (defaults to tool name). */
+    resolveOperation(toolName) {
+        return this.sideEffecting.get(toolName)?.operation ?? toolName;
+    }
+    /** Resolve requested spend cents for a registered side-effecting tool. */
+    resolveSpendCents(toolName, args) {
+        const entry = this.sideEffecting.get(toolName);
+        if (!entry?.spendCents) {
+            return undefined;
+        }
+        if (typeof entry.spendCents === "number") {
+            return entry.spendCents;
+        }
+        return entry.spendCents(args);
+    }
+    /** Lookup side-effecting entry by tool name. */
+    getSideEffectingEntry(toolName) {
+        return this.sideEffecting.get(toolName);
+    }
+    /** Registered side-effecting tool names. */
+    sideEffectingToolNames() {
+        return [...this.sideEffecting.keys()];
+    }
+    /** Registered Harbor operations for side-effecting tools. */
+    sideEffectingOperations() {
+        return [...this.operations];
+    }
+    /**
+     * Classify a tool call for interceptor routing.
+     * When `defaultDeny` is true, unregistered tools whose operation is in `allowedTools` are denied.
+     */
+    resolveTool(toolName, options) {
+        const entry = this.sideEffecting.get(toolName);
+        if (entry) {
+            return {
+                kind: "side_effecting",
+                toolName,
+                operation: entry.operation,
+                entry,
+            };
+        }
+        const operation = this.resolveOperation(toolName);
+        if (this.defaultDeny &&
+            options?.allowedTools !== undefined &&
+            options.allowedTools.includes(operation)) {
+            return {
+                kind: "denied",
+                toolName,
+                operation,
+                reason: "unregistered_side_effecting",
+            };
+        }
+        return { kind: "passthrough", toolName };
+    }
+    /**
+     * Bind-time validation: when `defaultDeny` is enabled, every intent allowed operation
+     * must have a registered side-effecting tool entry.
+     */
+    validateForBind(allowedTools) {
+        if (!this.defaultDeny) {
+            return;
+        }
+        for (const operation of allowedTools) {
+            if (!this.operations.has(operation)) {
+                throw new PaybondToolRegistryValidationError(`defaultDeny: operation "${operation}" is in intent allowedTools but not registered as side-effecting`);
+            }
+        }
+    }
+}
+/** Create a validated tool registry for agent middleware. */
+export function createPaybondToolRegistry(config) {
+    return new PaybondToolRegistry(config);
+}

package/dist/agent/run.d.ts

@@ -0,0 +1,124 @@
+import { PaybondToolInterceptor } from "./interceptor.js";
+import { PaybondToolRegistry } from "./registry.js";
+import { PaybondRunBinding, PaybondAgentRunBindInput, PaybondRunGuard } from "./types.js";
+import type { PaybondPolicySnapshot } from "../policy/snapshot.js";
+import { type PaybondPolicyReloadFailedEvent, type PaybondPolicyReloadOptions, type PaybondPolicyReloadedEvent, type PaybondPolicyReloadResult } from "../policy/reload.js";
+type SandboxBootstrapResult = {
+    tenant_id: string;
+    intent_id: string;
+    capability_token: string;
+    operation: string;
+    requested_spend_cents: number;
+    sandbox_lifecycle_status: string;
+};
+type SandboxGuardrailEvidenceResult = {
+    tenant_id: string;
+    intent_id: string;
+    sandbox_lifecycle_status: string;
+    predicate_passed?: boolean | null;
+};
+export type PaybondSubmitProductionEvidenceInput = {
+    intentId: string;
+    payload: Record<string, unknown>;
+    vendorPayload?: Record<string, unknown>;
+    operation: string;
+    requestedSpendCents: number;
+    idempotencyKey: string;
+};
+type AgentRunHarbor = {
+    tenantId: string;
+    getIntent(intentId: string): Promise<Record<string, unknown>>;
+    submitEvidence(intentId: string, evidenceBody: Record<string, unknown>, options: {
+        idempotencyKey?: string;
+        recognitionProof: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+};
+type AgentRunGuardrails = {
+    bootstrapSandbox(input: {
+        operation: string;
+        requestedSpendCents: number;
+        currency?: string;
+        evidenceSchema?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+        idempotencyKey?: string;
+        completionPreset?: string;
+        templateId?: string;
+        parameters?: Record<string, unknown>;
+    }): Promise<SandboxBootstrapResult>;
+    submitSandboxEvidence(input: {
+        intentId: string;
+        payload?: Record<string, unknown>;
+        vendorPayload?: Record<string, unknown>;
+        operation?: string;
+        requestedSpendCents?: number;
+        metadata?: Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<SandboxGuardrailEvidenceResult>;
+};
+/** Minimal Paybond session surface required to bind an agent run. */
+export type PaybondAgentRunHost = {
+    harbor: AgentRunHarbor;
+    guardrails: AgentRunGuardrails;
+    spendGuard(intentId: string, capabilityToken: string): PaybondRunGuard;
+};
+type PolicyReloadEventMap = {
+    policyReloaded: PaybondPolicyReloadedEvent;
+    policyReloadFailed: PaybondPolicyReloadFailedEvent;
+};
+/**
+ * Run-scoped agent middleware context for one agent task.
+ * Bind once per run; do not share across concurrent agent tasks.
+ */
+export declare class PaybondAgentRun {
+    private _currentSnapshot?;
+    readonly binding: PaybondRunBinding;
+    readonly interceptor: PaybondToolInterceptor;
+    readonly policyFilePath?: string;
+    private reloadController?;
+    private readonly approvalTokens;
+    private readonly listeners;
+    private constructor();
+    /** Start file watcher and/or Gateway poll reload (called from bind when `reload` is set). */
+    startPolicyReload(config: import("../policy/reload.js").PaybondPolicyReloadBindConfig): void;
+    /** Active policy snapshot for this run (undefined when bind omitted policy tracking). */
+    get currentSnapshot(): PaybondPolicySnapshot | undefined;
+    /** `sha256:<hex>` digest of the active policy snapshot, when tracked. */
+    get policyDigest(): string | undefined;
+    /** `{policy_name}@{digest_short}` version label of the active snapshot. */
+    get policyVersion(): string | undefined;
+    /** RFC3339 timestamp when the active policy snapshot was loaded. */
+    get policyLoadedAt(): string | undefined;
+    /** Active in-flight authorize/execute cycles (blocks policy reload until zero). */
+    get inFlightCount(): number;
+    get runId(): string;
+    get tenantId(): string;
+    get intentId(): string;
+    get capabilityToken(): string;
+    get guard(): PaybondRunGuard;
+    get registry(): PaybondToolRegistry;
+    get allowedTools(): readonly string[];
+    /** Subscribe to policy reload lifecycle events. */
+    on<K extends keyof PolicyReloadEventMap>(event: K, listener: (payload: PolicyReloadEventMap[K]) => void): void;
+    /** Unsubscribe from policy reload lifecycle events. */
+    off<K extends keyof PolicyReloadEventMap>(event: K, listener: (payload: PolicyReloadEventMap[K]) => void): void;
+    private emit;
+    /** Atomically swap registry and snapshot on the run binding (Tier 7 hot-reload). */
+    applyPolicySnapshot(snapshot: PaybondPolicySnapshot): void;
+    /** Reload policy from disk or Gateway effective resolution without re-binding the run. */
+    reloadPolicy(options?: PaybondPolicyReloadOptions): Promise<PaybondPolicyReloadResult>;
+    /** Stop background reload watchers started at bind time. */
+    stopPolicyReload(): void;
+    /** Store an operator approval token for retry after a Harbor approval hold. */
+    storeApprovalToken(toolCallId: string, token: string): void;
+    /** Read a stored approval token for a tool call retry. */
+    getApprovalToken(toolCallId: string): string | undefined;
+    /** Bind a run-scoped middleware context via sandbox bootstrap or attach. */
+    static bind(paybond: PaybondAgentRunHost, input: PaybondAgentRunBindInput): Promise<PaybondAgentRun>;
+}
+/** Facade exposed as `paybond.agentRun`. */
+export declare class PaybondAgentRunFacade {
+    private readonly paybond;
+    constructor(paybond: PaybondAgentRunHost);
+    bind(input: PaybondAgentRunBindInput): Promise<PaybondAgentRun>;
+}
+export {};