@paybond/kit 0.9.8 → 0.11.0

package/dist/agent/interceptor.js

@@ -0,0 +1,440 @@
+import { evictExpiredAuthorizationCache, takeValidCachedAuthorization, } from "./authorization-cache.js";
+import { buildAutoEvidencePayload } from "./evidence.js";
+import { signHarborEvidenceSubmitRecognitionProof } from "../agent-recognition.js";
+import { signPayeeEvidenceBinding } from "../payee-evidence.js";
+import { PaybondAutoEvidenceSubmitError, PaybondUnregisteredSideEffectingToolError, } from "./types.js";
+export { PaybondAutoEvidenceSubmitError, PaybondEvidenceSubmitError } from "./types.js";
+function nowRfc3339Seconds() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function traceTimestamp() {
+    return new Date().toISOString();
+}
+function evidenceIdempotencyKey(intentId, toolCallId) {
+    return `evidence:${intentId}:${toolCallId}`;
+}
+function authorizationCacheKey(toolCallId, operation) {
+    return `${toolCallId}:${operation}`;
+}
+function assertOperationAllowed(operation, allowedTools) {
+    if (!allowedTools.includes(operation)) {
+        throw new Error(`operation "${operation}" is not in bound intent allowedTools (${allowedTools.join(", ")})`);
+    }
+}
+function mapSandboxEvidenceResult(result) {
+    return {
+        submitted: true,
+        intentId: result.intent_id,
+        predicatePassed: result.predicate_passed ?? undefined,
+        sandboxLifecycleStatus: result.sandbox_lifecycle_status,
+    };
+}
+function isSpendApprovalRequiredError(err) {
+    return err instanceof Error && err.name === "PaybondSpendApprovalRequiredError";
+}
+function isSpendDeniedError(err) {
+    return err instanceof Error && err.name === "PaybondSpendDeniedError";
+}
+function mapSpendErrorToDecision(err, operation, kind) {
+    const result = err.result;
+    const message = result?.message ??
+        result?.code ??
+        err.message ??
+        (kind === "approval_required" ? "approval_required" : "denied");
+    const base = {
+        message,
+        operation,
+        auditId: result?.auditId,
+        code: result?.code,
+    };
+    return kind === "approval_required"
+        ? { kind: "approval_required", ...base }
+        : { kind: "deny", ...base };
+}
+/**
+ * Pre/post intercept for side-effecting tools: authorize, execute, finalize spend, auto-evidence.
+ */
+export class PaybondToolInterceptor {
+    binding;
+    host;
+    authorizedCalls = new Map();
+    _inFlightCount = 0;
+    constructor(binding, host) {
+        this.binding = binding;
+        this.host = host;
+    }
+    /** Active in-flight authorize/execute cycles (blocks policy reload until zero). */
+    get inFlightCount() {
+        return this._inFlightCount;
+    }
+    beginInFlight() {
+        this._inFlightCount += 1;
+        return this.binding.policySnapshot?.digest;
+    }
+    endInFlight() {
+        this._inFlightCount = Math.max(0, this._inFlightCount - 1);
+    }
+    emitTrace(event) {
+        this.binding.onTrace?.(event);
+    }
+    /** Authorize-only pre-execution check for framework tool input guardrails. */
+    async authorizeToolCall(input) {
+        const toolName = input.toolName.trim();
+        const toolCallId = input.toolCallId.trim();
+        if (!toolName) {
+            throw new Error("toolName must be non-empty");
+        }
+        if (!toolCallId) {
+            throw new Error("toolCallId must be non-empty");
+        }
+        const pinnedDigest = this.beginInFlight();
+        try {
+            const resolution = this.binding.registry.resolveTool(toolName, {
+                allowedTools: this.binding.allowedTools,
+            });
+            if (resolution.kind === "passthrough") {
+                return { kind: "allow", passthrough: true, operation: toolName };
+            }
+            if (resolution.kind === "denied") {
+                return {
+                    kind: "deny",
+                    operation: resolution.operation,
+                    message: `side-effecting tool "${resolution.toolName}" (operation "${resolution.operation}") is in intent allowedTools but not registered`,
+                };
+            }
+            let resolved;
+            try {
+                resolved = this.resolveSideEffectingCall(input, resolution.entry, resolution.operation);
+            }
+            catch (err) {
+                if (err instanceof Error) {
+                    return { kind: "deny", message: err.message, operation: resolution.operation };
+                }
+                throw err;
+            }
+            this.emitTrace({
+                type: "tool_selected",
+                runId: this.binding.runId,
+                toolName: resolved.toolName,
+                toolCallId: resolved.toolCallId,
+                operation: resolved.operation,
+                recordedAt: traceTimestamp(),
+            });
+            try {
+                const auth = await this.binding.guard.assertSpendAuthorized(resolved.authInput);
+                evictExpiredAuthorizationCache(this.authorizedCalls);
+                this.authorizedCalls.set(authorizationCacheKey(toolCallId, resolved.operation), {
+                    auth,
+                    policyDigest: pinnedDigest,
+                    operation: resolved.operation,
+                    requestedSpendCents: resolved.requestedSpendCents,
+                    toolName: resolved.toolName,
+                    cachedAtMs: Date.now(),
+                });
+                this.emitTrace({
+                    type: "spend_authorized",
+                    runId: this.binding.runId,
+                    toolCallId: resolved.toolCallId,
+                    operation: resolved.operation,
+                    auditId: auth.auditId,
+                    decisionId: auth.decisionId,
+                    amountCents: resolved.requestedSpendCents,
+                    recordedAt: traceTimestamp(),
+                });
+                return {
+                    kind: "allow",
+                    operation: resolved.operation,
+                    auditId: auth.auditId,
+                    decisionId: auth.decisionId,
+                    policyDigest: pinnedDigest,
+                };
+            }
+            catch (err) {
+                if (isSpendApprovalRequiredError(err)) {
+                    const decision = mapSpendErrorToDecision(err, resolved.operation, "approval_required");
+                    if (decision.kind === "approval_required") {
+                        this.emitTrace({
+                            type: "approval_required",
+                            runId: this.binding.runId,
+                            toolCallId: resolved.toolCallId,
+                            operation: resolved.operation,
+                            message: decision.message,
+                            auditId: decision.auditId,
+                            code: decision.code,
+                            recordedAt: traceTimestamp(),
+                        });
+                    }
+                    return decision;
+                }
+                if (isSpendDeniedError(err)) {
+                    const decision = mapSpendErrorToDecision(err, resolved.operation, "deny");
+                    if (decision.kind === "deny") {
+                        this.emitTrace({
+                            type: "spend_denied",
+                            runId: this.binding.runId,
+                            toolCallId: resolved.toolCallId,
+                            operation: resolved.operation,
+                            message: decision.message,
+                            auditId: decision.auditId,
+                            code: decision.code,
+                            recordedAt: traceTimestamp(),
+                        });
+                    }
+                    return decision;
+                }
+                throw err;
+            }
+        }
+        finally {
+            this.endInFlight();
+        }
+    }
+    /** Run one tool through the middleware authorize → execute → evidence cycle. */
+    async wrapExecute(input) {
+        const toolName = input.toolName.trim();
+        const toolCallId = input.toolCallId.trim();
+        if (!toolName) {
+            throw new Error("toolName must be non-empty");
+        }
+        if (!toolCallId) {
+            throw new Error("toolCallId must be non-empty");
+        }
+        const pinnedDigest = this.beginInFlight();
+        try {
+            const resolution = this.binding.registry.resolveTool(toolName, {
+                allowedTools: this.binding.allowedTools,
+            });
+            if (resolution.kind === "passthrough") {
+                return { toolResult: await input.execute() };
+            }
+            if (resolution.kind === "denied") {
+                throw new PaybondUnregisteredSideEffectingToolError(resolution.toolName, resolution.operation);
+            }
+            const resolved = this.resolveSideEffectingCall(input, resolution.entry, resolution.operation);
+            this.emitTrace({
+                type: "tool_selected",
+                runId: this.binding.runId,
+                toolName: resolved.toolName,
+                toolCallId: resolved.toolCallId,
+                operation: resolved.operation,
+                recordedAt: traceTimestamp(),
+            });
+            const cacheKey = authorizationCacheKey(toolCallId, resolved.operation);
+            const cached = takeValidCachedAuthorization(this.authorizedCalls, cacheKey, {
+                operation: resolved.operation,
+                requestedSpendCents: resolved.requestedSpendCents,
+                toolName: resolved.toolName,
+            });
+            const evidencePolicyDigest = cached?.policyDigest ?? pinnedDigest;
+            let auth;
+            if (cached) {
+                auth = cached.auth;
+            }
+            else {
+                auth = await this.binding.guard.assertSpendAuthorized(resolved.authInput);
+                this.emitTrace({
+                    type: "spend_authorized",
+                    runId: this.binding.runId,
+                    toolCallId: resolved.toolCallId,
+                    operation: resolved.operation,
+                    auditId: auth.auditId,
+                    decisionId: auth.decisionId,
+                    amountCents: resolved.requestedSpendCents,
+                    recordedAt: traceTimestamp(),
+                });
+            }
+            const executeStartedAt = Date.now();
+            try {
+                const toolResult = await input.execute();
+                this.emitTrace({
+                    type: "tool_executed",
+                    runId: this.binding.runId,
+                    toolCallId: resolved.toolCallId,
+                    operation: resolved.operation,
+                    durationMs: Date.now() - executeStartedAt,
+                    recordedAt: traceTimestamp(),
+                });
+                if (auth.decisionId) {
+                    await this.binding.guard.completeSpendAuthorization(auth.decisionId, "consumed");
+                    this.emitTrace({
+                        type: "spend_finalized",
+                        runId: this.binding.runId,
+                        toolCallId: resolved.toolCallId,
+                        operation: resolved.operation,
+                        status: "consumed",
+                        recordedAt: traceTimestamp(),
+                    });
+                }
+                const evidenceId = evidenceIdempotencyKey(this.binding.intentId, toolCallId);
+                const evidence = await this.submitAutoEvidence({
+                    entry: resolved.entry,
+                    toolName,
+                    toolCallId,
+                    operation: resolved.operation,
+                    arguments: input.arguments,
+                    requestedSpendCents: resolved.requestedSpendCents,
+                    toolResult,
+                    auth,
+                    evidenceId,
+                });
+                this.emitTrace({
+                    type: "evidence_submitted",
+                    runId: this.binding.runId,
+                    toolCallId: resolved.toolCallId,
+                    operation: resolved.operation,
+                    evidenceId,
+                    presetId: resolved.entry.evidencePreset,
+                    evidencePreset: resolved.entry.evidencePreset,
+                    sandboxLifecycleStatus: evidence.sandboxLifecycleStatus,
+                    predicatePassed: evidence.predicatePassed,
+                    recordedAt: traceTimestamp(),
+                });
+                return {
+                    toolResult,
+                    authorization: {
+                        allow: true,
+                        auditId: auth.auditId,
+                        decisionId: auth.decisionId,
+                        policyDigest: evidencePolicyDigest,
+                    },
+                    evidence,
+                };
+            }
+            catch (err) {
+                if (err instanceof PaybondAutoEvidenceSubmitError) {
+                    throw err;
+                }
+                if (auth.decisionId) {
+                    try {
+                        await this.binding.guard.completeSpendAuthorization(auth.decisionId, "released");
+                        this.emitTrace({
+                            type: "spend_finalized",
+                            runId: this.binding.runId,
+                            toolCallId: resolved.toolCallId,
+                            operation: resolved.operation,
+                            status: "released",
+                            recordedAt: traceTimestamp(),
+                        });
+                    }
+                    catch {
+                        // Best-effort release when the guarded handler fails.
+                    }
+                }
+                throw err;
+            }
+        }
+        finally {
+            this.endInFlight();
+        }
+    }
+    resolveSideEffectingCall(input, entry, defaultOperation) {
+        const toolName = input.toolName.trim();
+        const toolCallId = input.toolCallId.trim();
+        const operation = (input.operation ?? defaultOperation).trim();
+        assertOperationAllowed(operation, this.binding.allowedTools);
+        const requestedSpendCents = input.requestedSpendCents ??
+            this.binding.registry.resolveSpendCents(toolName, input.arguments) ??
+            0;
+        return {
+            toolName,
+            toolCallId,
+            operation,
+            requestedSpendCents,
+            entry,
+            authInput: {
+                operation,
+                requestedSpendCents,
+                toolCallId,
+                toolName,
+                vendorId: input.vendorId,
+                taskId: input.taskId,
+                workflowId: input.workflowId,
+                currency: input.currency,
+                agentSubject: input.agentSubject,
+                approvalToken: input.approvalToken,
+                idempotencyKey: input.idempotencyKey,
+            },
+        };
+    }
+    async submitAutoEvidence(options) {
+        const ctx = {
+            toolName: options.toolName,
+            toolCallId: options.toolCallId,
+            operation: options.operation,
+            arguments: options.arguments,
+        };
+        let payload;
+        try {
+            payload = buildAutoEvidencePayload(options.entry, options.toolResult, ctx);
+        }
+        catch (err) {
+            throw new PaybondAutoEvidenceSubmitError(options.toolResult, err);
+        }
+        const idempotencyKey = options.evidenceId;
+        try {
+            if (this.binding.sandbox) {
+                const result = await this.host.guardrails.submitSandboxEvidence({
+                    intentId: this.binding.intentId,
+                    payload,
+                    operation: options.operation,
+                    requestedSpendCents: options.requestedSpendCents,
+                    metadata: {
+                        tool_name: options.toolName,
+                        tool_call_id: options.toolCallId,
+                        evidence_preset: options.entry.evidencePreset,
+                        decision_id: options.auth.decisionId,
+                    },
+                    idempotencyKey,
+                });
+                return mapSandboxEvidenceResult(result);
+            }
+            const productionEvidence = this.binding.productionEvidence;
+            if (!productionEvidence) {
+                throw new Error("production agent run bind requires attach.productionEvidence for auto-evidence submission");
+            }
+            const wire = signPayeeEvidenceBinding({
+                tenantId: this.binding.tenantId,
+                intentId: this.binding.intentId,
+                payeeDid: productionEvidence.payeeDid,
+                payload,
+                artifactsBlake3Hex: [],
+                submittedAtRfc3339: nowRfc3339Seconds(),
+                payeeSigningSeed: productionEvidence.payeeSigningSeed,
+            });
+            const recognitionProof = signHarborEvidenceSubmitRecognitionProof({
+                tenantId: this.binding.tenantId,
+                intentId: this.binding.intentId,
+                evidenceBody: wire,
+                keyId: productionEvidence.agentRecognitionKeyId,
+                signingSeed: productionEvidence.agentRecognitionSigningSeed,
+            });
+            const result = await this.host.harbor.submitEvidence(this.binding.intentId, wire, {
+                idempotencyKey,
+                recognitionProof,
+            });
+            const resultRecord = result;
+            const intentState = typeof resultRecord.intent_state === "string"
+                ? resultRecord.intent_state
+                : typeof resultRecord.state === "string"
+                    ? resultRecord.state
+                    : undefined;
+            const predicatePassed = typeof resultRecord.predicate_passed === "boolean"
+                ? resultRecord.predicate_passed
+                : typeof resultRecord.predicatePassed === "boolean"
+                    ? resultRecord.predicatePassed
+                    : undefined;
+            return {
+                submitted: true,
+                intentId: this.binding.intentId,
+                intentState,
+                predicatePassed,
+            };
+        }
+        catch (err) {
+            if (err instanceof PaybondAutoEvidenceSubmitError) {
+                throw err;
+            }
+            throw new PaybondAutoEvidenceSubmitError(options.toolResult, err);
+        }
+    }
+}

package/dist/agent/lazy-context-tools.d.ts

@@ -0,0 +1,15 @@
+export declare const PAYBOND_LAZY_CONTEXT_MESSAGE = "context provider must return { intentId, capabilityToken } for the active request before executing side-effecting tools.";
+/** Thrown when a lazy-context provider returns incomplete binding material. */
+export declare class PaybondLazyContextError extends Error {
+    constructor(message?: string);
+}
+export type LazyRuntimeResolver<TTools = unknown> = {
+    resolve: () => Promise<{
+        tools: TTools;
+    }>;
+};
+/**
+ * Wrap tools so each execution resolves request context via {@link LazyRuntimeResolver}.
+ * Safe to register once; binding happens per active request at execute time.
+ */
+export declare function wrapLazyContextTools<TTools>(rawTools: TTools, resolver: LazyRuntimeResolver<TTools>): TTools;

package/dist/agent/lazy-context-tools.js

@@ -0,0 +1,81 @@
+export const PAYBOND_LAZY_CONTEXT_MESSAGE = "context provider must return { intentId, capabilityToken } for the active request before executing side-effecting tools.";
+/** Thrown when a lazy-context provider returns incomplete binding material. */
+export class PaybondLazyContextError extends Error {
+    constructor(message = PAYBOND_LAZY_CONTEXT_MESSAGE) {
+        super(message);
+        this.name = "PaybondLazyContextError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isGenericToolDefinition(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return typeof value.name === "string" && value.name.trim().length > 0 && typeof value.execute === "function";
+}
+async function executeGuardedTool(runtimeTools, toolName, call) {
+    if (Array.isArray(runtimeTools)) {
+        const tool = runtimeTools.find((entry) => isGenericToolDefinition(entry) && entry.name === toolName);
+        if (!tool) {
+            throw new Error(`guarded tool not found after lazy bind: ${toolName}`);
+        }
+        return tool.execute(call);
+    }
+    if (isRecord(runtimeTools)) {
+        const tool = runtimeTools[toolName];
+        if (typeof tool === "function") {
+            return tool(call);
+        }
+        if (isGenericToolDefinition(tool)) {
+            return tool.execute(call);
+        }
+    }
+    throw new Error(`guarded tool not found after lazy bind: ${toolName}`);
+}
+/**
+ * Wrap tools so each execution resolves request context via {@link LazyRuntimeResolver}.
+ * Safe to register once; binding happens per active request at execute time.
+ */
+export function wrapLazyContextTools(rawTools, resolver) {
+    const runGuarded = async (toolName, call) => {
+        const runtime = await resolver.resolve();
+        return executeGuardedTool(runtime.tools, toolName, call);
+    };
+    if (Array.isArray(rawTools)) {
+        return rawTools.map((tool) => {
+            if (!isGenericToolDefinition(tool)) {
+                return tool;
+            }
+            const { execute: _ignored, ...rest } = tool;
+            return {
+                ...rest,
+                name: tool.name,
+                execute: async (call) => runGuarded(tool.name, call),
+            };
+        });
+    }
+    if (isRecord(rawTools)) {
+        const wrapped = {};
+        for (const [name, tool] of Object.entries(rawTools)) {
+            if (typeof tool === "function") {
+                wrapped[name] = async (call) => runGuarded(name, call);
+                continue;
+            }
+            if (isGenericToolDefinition(tool)) {
+                const toolName = tool.name.trim() || name;
+                const { execute: _ignored, ...rest } = tool;
+                wrapped[name] = {
+                    ...rest,
+                    name: toolName,
+                    execute: async (call) => runGuarded(toolName, call),
+                };
+                continue;
+            }
+            wrapped[name] = tool;
+        }
+        return wrapped;
+    }
+    return rawTools;
+}

package/dist/agent/registry-file.d.ts

@@ -0,0 +1,39 @@
+import { PaybondToolRegistry } from "./registry.js";
+import { PaybondToolRegistryConfig } from "./types.js";
+export type AgentRegistryFileDocument = {
+    version?: number;
+    default_deny?: boolean;
+    defaultDeny?: boolean;
+    tools?: Record<string, AgentRegistryToolEntry>;
+};
+export type AgentRegistryToolEntry = {
+    side_effecting?: boolean;
+    sideEffecting?: boolean;
+    evidence_preset?: string;
+    evidencePreset?: string;
+    operation?: string;
+};
+export type AgentRegistryValidationIssue = {
+    code: string;
+    message: string;
+    tool?: string;
+};
+export type AgentRegistryValidationResult = {
+    ok: boolean;
+    version: number | null;
+    default_deny: boolean;
+    tool_count: number;
+    side_effecting_count: number;
+    issues: AgentRegistryValidationIssue[];
+    registry?: PaybondToolRegistry;
+};
+/** Parse registry file text (JSON or YAML). */
+export declare function parseAgentRegistryText(text: string, sourceLabel?: string): AgentRegistryFileDocument;
+/** Load and parse a registry file from disk. */
+export declare function loadAgentRegistryFile(path: string): Promise<AgentRegistryFileDocument>;
+/** Convert a registry file document into middleware registry config. */
+export declare function agentRegistryDocumentToConfig(doc: AgentRegistryFileDocument): PaybondToolRegistryConfig;
+/** Validate registry document semantics before bind or smoke tests. */
+export declare function validateAgentRegistryDocument(doc: AgentRegistryFileDocument): AgentRegistryValidationResult;
+/** Build a single-tool registry for sandbox smoke when no registry file is supplied. */
+export declare function buildSmokeRegistry(operation: string, evidencePresetId: string): PaybondToolRegistry;