@paybond/kit 0.10.0 → 0.11.1

package/dist/index.js

@@ -2,8 +2,15 @@
  * Paybond Kit — TypeScript Gateway client with tenant binding, retries, capability verification,
  * and signed intent/evidence helpers.
  */
-import { buildSignedCreateIntentBody, } from "./principal-intent.js";
+import { buildSignedCreateIntentBody, buildSignedCreateIntentBodyWithPolicyBinding, } from "./principal-intent.js";
 import { signPayeeEvidenceBinding } from "./payee-evidence.js";
+import { PaybondAgentRunFacade, PaybondInstrumentBuilder, createGuardedAgent, createGuardedAgentRunner, createPaybondAgent, createPaybondToolRegistry, instrumentPaybondAgent, instrumentPaybondClaudeAgents, instrumentPaybondLangGraph, instrumentPaybondMCP, instrumentPaybondOpenAI, instrumentPaybondVercel, resolveAgentPolicySource, wrapPaybondTools, } from "./agent/index.js";
+import { GatewayAgentRunTraceReporter, } from "./agent/gateway-trace-reporter.js";
+import { parsePolicyRemoteValidateResponse, policyValidateQueryString, } from "./policy/validate-remote.js";
+import { parsePolicyEffectiveResolveResponse, } from "./policy/load-effective.js";
+import { paybondPolicyPresets } from "./policy/policy-api.js";
+import { paybondSolutionPresets } from "./solutions/api.js";
+import { requireSecureGatewayUrl } from "./gateway-url.js";
 function parseVerifyCapabilityBody(body, expectedTenant, expectedIntentId) {
     const tenant = String(body.tenant ?? "");
     const intentId = String(body.intent_id ?? "");
@@ -78,7 +85,7 @@ function verifyCapabilityPayload(input) {
 export const DEFAULT_PAYBOND_GATEWAY_BASE_URL = "https://api.paybond.ai";
 function defaultGatewayBaseUrl(value) {
     const trimmed = value?.trim();
-    return trimmed ? trimmed : DEFAULT_PAYBOND_GATEWAY_BASE_URL;
+    return requireSecureGatewayUrl(trimmed || DEFAULT_PAYBOND_GATEWAY_BASE_URL);
 }
 /**
  * Structured HTTP failure from Harbor with operator-facing diagnostics.
@@ -178,7 +185,7 @@ function protocolHTTPErrorMessage(prefix, statusCode, bodyText) {
     return `${prefix} HTTP ${statusCode}: ${bodyText}`;
 }
 function normalizeBase(url) {
-    return url.trim().replace(/\/+$/, "");
+    return requireSecureGatewayUrl(url);
 }
 function backoffMs(attempt) {
     const base = 200 * 2 ** attempt;
@@ -293,6 +300,18 @@ export class PaybondSpendGuard {
         }
         await complete.call(this.harbor, { decisionId, outcome });
     }
+    /**
+     * Authorize spend for `input.operation`, then invoke `handler`.
+     *
+     * The `operation` label and `requestedSpendCents` are sent to Harbor for
+     * policy evaluation only. This wrapper does not inspect or constrain what
+     * `handler` actually does — callers must keep the authorization label,
+     * spend amount, and handler side effects aligned with the bound intent's
+     * `allowedTools` and policy predicates.
+     *
+     * For registry-backed operation-to-handler coupling, prefer
+     * `paybond.instrument()` or `wrapTools()` over per-tool `guardTool`.
+     */
     guardTool(input, handler) {
         return async (...args) => {
             const auth = await this.assertSpendAuthorized(input);
@@ -320,6 +339,7 @@ export class PaybondSpendGuard {
 export async function authorizeSpend(source, input) {
     return new PaybondSpendGuard(source).authorizeSpend(input);
 }
+/** Standalone alias for {@link PaybondSpendGuard.guardTool}. */
 export function guardTool(source, input, handler) {
     return new PaybondSpendGuard(source).guardTool(input, handler);
 }
@@ -356,7 +376,24 @@ export function paybondRuntimeToolCallAdapter(init) {
             }
             throw new PaybondSpendDeniedError(result);
         }
-        return await init.execute(call);
+        try {
+            const out = await init.execute(call);
+            if (result.decisionId) {
+                await guard.completeSpendAuthorization(result.decisionId, "consumed");
+            }
+            return out;
+        }
+        catch (err) {
+            if (result.decisionId) {
+                try {
+                    await guard.completeSpendAuthorization(result.decisionId, "released");
+                }
+                catch {
+                    // Best-effort release when the guarded handler fails.
+                }
+            }
+            throw err;
+        }
     };
 }
 /**
@@ -791,9 +828,15 @@ export class GatewayHarborClient {
         throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
     }
     async postJSON(path, payload, extraHeaders) {
+        return this.requestJSON("POST", path, payload, extraHeaders);
+    }
+    async putJSON(path, payload, extraHeaders) {
+        return this.requestJSON("PUT", path, payload, extraHeaders);
+    }
+    async requestJSON(method, path, payload, extraHeaders) {
         const url = `${this.base}${path.replace(/^\/+/, "")}`;
         const res = await this.fetchWithRetries(url, {
-            method: "POST",
+            method,
             headers: this.headers({
                 "content-type": "application/json",
                 ...(extraHeaders ?? {}),
@@ -803,6 +846,65 @@ export class GatewayHarborClient {
         const text = await res.text();
         return { res, text, url };
     }
+    async getJSON(path) {
+        const url = `${this.base}${path.replace(/^\/+/, "")}`;
+        const res = await this.fetchWithRetries(url, {
+            method: "GET",
+            headers: this.headers(),
+        });
+        const text = await res.text();
+        return { res, text, url };
+    }
+    /** Tenant-scoped Harbor operator intent detail (for attach run binding). */
+    async getIntent(intentId) {
+        const trimmed = intentId.trim();
+        if (!trimmed) {
+            throw new Error("getIntent requires a non-empty intentId");
+        }
+        const { res, text, url } = await this.getJSON(`/harbor/operator/v1/intents/${encodeURIComponent(trimmed)}`);
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway Harbor get intent HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = JSON.parse(text);
+        const tenant = String(body.tenant_id ?? "").trim();
+        if (tenant !== this.tenantId) {
+            throw new Error(`intent tenant mismatch: client=${this.tenantId} gateway=${tenant}`);
+        }
+        return body;
+    }
+    /** Gateway-backed middleware trace reporter for tenant console agent-runs view. */
+    createAgentRunTraceReporter(runId) {
+        const trimmed = runId.trim();
+        if (!trimmed) {
+            throw new Error("createAgentRunTraceReporter requires a non-empty runId");
+        }
+        return new GatewayAgentRunTraceReporter(async (method, path, body) => {
+            if (method === "PUT") {
+                const { res, text, url } = await this.putJSON(path, body);
+                if (!res.ok) {
+                    throw new HarborHttpError(`Gateway agent run upsert HTTP ${res.status}: ${text}`, {
+                        statusCode: res.status,
+                        url,
+                        bodyText: text,
+                    });
+                }
+                return JSON.parse(text);
+            }
+            const { res, text, url } = await this.postJSON(path, body);
+            if (!res.ok) {
+                throw new HarborHttpError(`Gateway agent run trace HTTP ${res.status}: ${text}`, {
+                    statusCode: res.status,
+                    url,
+                    bodyText: text,
+                });
+            }
+            return JSON.parse(text);
+        }, trimmed);
+    }
     mutationHeaders(operation, options, headers) {
         const proof = options?.recognitionProof;
         if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
@@ -847,6 +949,42 @@ export class GatewayHarborClient {
             });
         }
     }
+    /**
+     * Validate a paybond.policy.yaml document against the tenant Harbor registry
+     * (`POST /v1/policy/validate`).
+     */
+    async validatePolicy(document, options) {
+        const qs = policyValidateQueryString(options ?? {});
+        const { res, text, url } = await this.postJSON(`/v1/policy/validate${qs}`, document);
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway policy validate HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return parsePolicyRemoteValidateResponse(JSON.parse(text));
+    }
+    /**
+     * Resolve merged effective policy for a tenant overlay via
+     * `POST /v1/org-policies/{policy_id}/effective`.
+     */
+    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 { res, text, url } = await this.postJSON(path, overlay);
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway policy effective HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return parsePolicyEffectiveResolveResponse(JSON.parse(text));
+    }
     async createIntent(body, options) {
         const { res, text, url } = await this.postJSON("/harbor/intents", body, this.mutationHeaders("createIntent", options));
         if (!res.ok) {
@@ -967,6 +1105,15 @@ export class PaybondGuardrails {
         if (input.metadata !== undefined) {
             payload.metadata = input.metadata;
         }
+        if (input.completionPreset !== undefined) {
+            payload.completion_preset = input.completionPreset;
+        }
+        if (input.templateId !== undefined) {
+            payload.template_id = input.templateId;
+        }
+        if (input.parameters !== undefined) {
+            payload.parameters = input.parameters;
+        }
         const { res, text, url } = await this.postJSON("/v1/sandbox/guardrails/bootstrap", payload, { idempotencyKey: input.idempotencyKey });
         if (!res.ok) {
             throw new HarborHttpError(`Gateway sandbox guardrail bootstrap HTTP ${res.status}: ${text}`, {
@@ -987,6 +1134,9 @@ export class PaybondGuardrails {
         if (input.payload !== undefined) {
             payload.payload = input.payload;
         }
+        if (input.vendorPayload !== undefined) {
+            payload.vendor_payload = input.vendorPayload;
+        }
         if (input.artifacts !== undefined) {
             payload.artifacts = input.artifacts;
         }
@@ -1137,9 +1287,32 @@ function parseSandboxGuardrailEvidenceResponse(value, init) {
             : undefined,
         payload_digest: sandboxGuardrailOptionalString(body.payload_digest),
         artifacts_digest: sandboxGuardrailOptionalString(body.artifacts_digest),
+        schema_validation: readSchemaValidationReport(body.schema_validation),
         simulator_event: body.simulator_event,
     };
 }
+function readSchemaValidationReport(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const report = value;
+    if (typeof report.vendor_schema_ok !== "boolean" || typeof report.canonical_schema_ok !== "boolean") {
+        return undefined;
+    }
+    const qualityFields = report.quality_fields_missing;
+    const driftKinds = report.drift_kinds;
+    return {
+        vendor_schema_ok: report.vendor_schema_ok,
+        canonical_schema_ok: report.canonical_schema_ok,
+        quality_fields_missing: Array.isArray(qualityFields)
+            ? qualityFields.filter((entry) => typeof entry === "string")
+            : [],
+        pack_stale: Boolean(report.pack_stale),
+        drift_kinds: Array.isArray(driftKinds)
+            ? driftKinds.filter((entry) => typeof entry === "string")
+            : [],
+    };
+}
 function sandboxGuardrailString(body, field, init) {
     const value = body[field];
     if (typeof value === "string" && value.trim()) {
@@ -2040,6 +2213,19 @@ export class PaybondIntents {
      * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be
      * 32 bytes. `settlementRail` is signed as the requested rail; destinations stay server-owned.
      */
+    async createWithPolicyBinding(params) {
+        const { idempotencyKey, intentId: maybeIntentId, recognitionProof, ...fields } = params;
+        const intentId = maybeIntentId ?? globalThis.crypto.randomUUID();
+        const body = buildSignedCreateIntentBodyWithPolicyBinding({
+            tenantId: this.harbor.tenantId,
+            intentId,
+            ...fields,
+        });
+        return this.harbor.createIntent(body, { idempotencyKey, recognitionProof });
+    }
+    /**
+     * Build a principal-signed `POST /intents` body and submit it (raw predicate_dsl, signing v6).
+     */
     async create(params) {
         const { idempotencyKey, intentId: maybeIntentId, recognitionProof, ...fields } = params;
         const intentId = maybeIntentId ?? globalThis.crypto.randomUUID();
@@ -2088,6 +2274,7 @@ export class Paybond {
     a2a;
     protocol;
     intents;
+    agentRun;
     constructor(harbor, guardrails, signal, fraud, a2a, protocol) {
         this.harbor = harbor;
         this.guardrails = guardrails;
@@ -2096,6 +2283,7 @@ export class Paybond {
         this.a2a = a2a;
         this.protocol = protocol;
         this.intents = new PaybondIntents(harbor);
+        this.agentRun = new PaybondAgentRunFacade(this);
     }
     /** Open a tenant-bound hosted Paybond session from a service-account API key. */
     static async open(init) {
@@ -2135,10 +2323,83 @@ export class Paybond {
     spendGuard(intentId, capabilityToken) {
         return new PaybondSpendGuard({ harbor: this.harbor, intentId, capabilityToken });
     }
+    /** Build a validated side-effecting tool registry for agent middleware. */
+    toolRegistry(config) {
+        return createPaybondToolRegistry(config);
+    }
     async authorizeSpend(input) {
         return this.harbor.authorizeSpend(input);
     }
+    /** Policy-driven agent factory: load policy, bind a run, and wire framework tools. */
+    createGuardedAgent(input) {
+        return createGuardedAgent(this, input);
+    }
+    /** Alias for {@link Paybond.createGuardedAgent} matching runner helper naming. */
+    createGuardedAgentRunner(input) {
+        return createGuardedAgentRunner(this, input);
+    }
+    instrument(input, options) {
+        return instrumentPaybondAgent(this, input, options);
+    }
+    /** Fluent builder: `paybond.policy("./paybond.policy.yaml").instrument(tools)`. */
+    policy(source) {
+        const resolved = typeof source === "string" ? resolveAgentPolicySource(source) : source;
+        return new PaybondInstrumentBuilder(this, resolved);
+    }
+    /** Fluent builder for bundled vertical presets (`travel`, `shopping`, `saas`, `aws`). */
+    usePolicy(presetId) {
+        return this.policy(presetId);
+    }
+    instrumentLangGraph(input) {
+        return instrumentPaybondLangGraph(this, input);
+    }
+    instrumentOpenAI(input) {
+        return instrumentPaybondOpenAI(this, input);
+    }
+    instrumentVercel(input) {
+        return instrumentPaybondVercel(this, input);
+    }
+    instrumentClaudeAgents(input) {
+        return instrumentPaybondClaudeAgents(this, input);
+    }
+    /** Agent-agnostic instrumentation for MCP-style `{ name, execute }` tool hosts. */
+    instrumentMCP(input) {
+        return instrumentPaybondMCP(this, input);
+    }
+    /**
+     * Opinionated quickstart: resolve named policy presets (for example `travel`) or file paths,
+     * then instrument tools for the selected framework.
+     */
+    agent(input) {
+        return createPaybondAgent(this, input);
+    }
+    /** Wrap tools for an existing bound run without reloading policy. */
+    wrapTools(run, tools, options) {
+        return wrapPaybondTools(run, tools, options);
+    }
+    /**
+     * Compose bundled policy presets (`travel`, `shopping`, …) and guardrail layers.
+     * Example: `paybond.policyPresets.travel({ maxSpendUsd: 500 })`.
+     */
+    get policyPresets() {
+        return paybondPolicyPresets;
+    }
+    /**
+     * Bundled solution references (`travel`, `shopping`, …) with policy, smoke defaults,
+     * completion preset, and vendor pack metadata.
+     * Example: `paybond.solution.travel()`.
+     */
+    get solution() {
+        return paybondSolutionPresets;
+    }
 }
 export { normalizeJson, jsonValueDigest } from "./json-digest.js";
-export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, } from "./principal-intent.js";
+export { buildSignedCreateIntentBody, buildSignedCreateIntentBodyWithPolicyBinding, intentCreationSignBytesRaw, intentCreationSignBytesWithPolicyBinding, } from "./principal-intent.js";
 export { artifactsDigest, signPayeeEvidenceBinding } from "./payee-evidence.js";
+export { AGENT_RECOGNITION_GATEWAY_VERIFIER_ID, AGENT_RECOGNITION_PROOF_KIND_V1, AGENT_RECOGNITION_PURPOSE_EVIDENCE_SUBMIT, newAgentRecognitionRequestEnvelope, signAgentRecognitionProofV1, signHarborEvidenceSubmitRecognitionProof, } from "./agent-recognition.js";
+export { validateCompletionEvidence, } from "./completion-validate-evidence.js";
+export { completionSchemaDigestHex, computeVendorContractDigests, verifyVendorContract, verifyCatalogVendorContracts, } from "./completion-contract-digest.js";
+export { contractSnapshotForPreset, mapVendorEvidenceToCanonical, resolveCompletionPreset, } from "./completion-resolve.js";
+export { PaybondAgentRun, PaybondAgentRunBindError, PaybondAgentRunFacade, PaybondEvidenceSubmitError, PaybondToolInterceptor, PaybondToolRegistry, PaybondToolRegistryValidationError, PaybondUnregisteredSideEffectingToolError, buildAutoEvidencePayload, createGenericToolExecutor, createGuardedAgent, createGuardedAgentRunner, createPaybondAgent, createPaybondGenericAgentConfig, createPaybondGenericInputGuard, createPaybondToolRegistry, createToolInputGuardAdapter, instrumentPaybondAgent, instrumentPaybondClaudeAgents, instrumentPaybondLangGraph, instrumentPaybondMCP, instrumentPaybondOpenAI, instrumentPaybondVercel, paybondGenericToolExecutorAdapter, paybondToolInputGuardAdapter, resolveAgentPolicySource, toPaybondAgentResult, wrapPaybondTools, PaybondInstrumentBuilder, PaybondInstrumented, PaybondInstrumentRuntime, PaybondLazyContextError, PaybondUnboundContextError, discoverPolicyFromAgent, discoverToolNames, discoverToolsFromAgent, inlinePolicyToDocument, isInlinePolicy, isInstrumentableAgentObject, readPaybondAgentInstrumentation, } from "./agent/index.js";
+export { PaybondPolicy, composePolicyLayers, composeBundledPresetDefault, domain, guardrails, paybondPolicyPresets, resolveComposedPresetDocument, } from "./policy/index.js";
+export { getSolutionSmokeDefaults, isKnownSolutionId, listSolutionIds, loadSolutionManifest, paybondSolutionPresets, } from "./solutions/index.js";