@paybond/kit 0.10.0 → 0.11.1

package/dist/gateway-url.d.ts

@@ -0,0 +1,7 @@
+export declare const LOCAL_GATEWAY_HOSTS: Set<string>;
+export declare class InsecureGatewayURLError extends Error {
+    constructor(message: string);
+}
+export declare function isLocalGatewayHost(hostname: string): boolean;
+/** Return a normalized gateway base URL or throw when TLS requirements are not met. */
+export declare function requireSecureGatewayUrl(url: string): string;

package/dist/gateway-url.js

@@ -0,0 +1,69 @@
+export const LOCAL_GATEWAY_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+export class InsecureGatewayURLError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InsecureGatewayURLError";
+    }
+}
+function parseIPv4Octets(ip) {
+    const parts = ip.trim().split(".");
+    if (parts.length !== 4) {
+        return null;
+    }
+    const octets = parts.map((part) => Number.parseInt(part, 10));
+    if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+        return null;
+    }
+    return octets;
+}
+/** True for loopback hostnames and RFC1918 private IPv4 addresses. */
+function isRfc1918IPv4(hostname) {
+    const octets = parseIPv4Octets(hostname);
+    if (!octets) {
+        return false;
+    }
+    const [first, second] = octets;
+    if (first === 10) {
+        return true;
+    }
+    if (first === 192 && second === 168) {
+        return true;
+    }
+    return first === 172 && second >= 16 && second <= 31;
+}
+export function isLocalGatewayHost(hostname) {
+    const lowered = hostname.trim().toLowerCase();
+    if (LOCAL_GATEWAY_HOSTS.has(lowered)) {
+        return true;
+    }
+    if (isRfc1918IPv4(lowered)) {
+        return true;
+    }
+    if (lowered.startsWith("127.")) {
+        return true;
+    }
+    return false;
+}
+/** Return a normalized gateway base URL or throw when TLS requirements are not met. */
+export function requireSecureGatewayUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        throw new InsecureGatewayURLError("gateway URL is required");
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new InsecureGatewayURLError("gateway URL must be an absolute URL");
+    }
+    const scheme = parsed.protocol.replace(":", "").toLowerCase();
+    const hostname = parsed.hostname.toLowerCase();
+    if (scheme === "https") {
+        return trimmed.replace(/\/+$/, "");
+    }
+    if (scheme === "http" && isLocalGatewayHost(hostname)) {
+        return trimmed.replace(/\/+$/, "");
+    }
+    throw new InsecureGatewayURLError("gateway URL must use https:// (http:// is allowed only for loopback and private networks)");
+}

package/dist/index.d.ts

@@ -2,8 +2,12 @@
  * Paybond Kit — TypeScript Gateway client with tenant binding, retries, capability verification,
  * and signed intent/evidence helpers.
  */
-import { type BuildSignedCreateIntentParams, type SettlementRail } from "./principal-intent.js";
+import { type BuildSignedCreateIntentParams, type BuildSignedCreateIntentWithPolicyBindingParams, type SettlementRail } from "./principal-intent.js";
 import { type SignPayeeEvidenceParams } from "./payee-evidence.js";
+import { PaybondAgentRunFacade, PaybondInstrumentBuilder, PaybondInstrumentRuntime, PaybondToolRegistry, type CreateGuardedAgentInput, type CreateGuardedAgentResult, type PaybondAgentInput, type PaybondAgentResult, type PaybondInlinePolicy, type PaybondInstrumentAgentOptions, type PaybondInstrumentInput, type PaybondInstrumented, type PaybondToolRegistryConfig, type PaybondWrapToolsOptions } from "./agent/index.js";
+import { GatewayAgentRunTraceReporter } from "./agent/gateway-trace-reporter.js";
+import { type PolicyRemoteValidateOptions, type PolicyRemoteValidateResult } from "./policy/validate-remote.js";
+import { type PolicyEffectiveResolveResult } from "./policy/load-effective.js";
 export type SpendScope = {
     scope_type: string;
     scope_key: string;
@@ -105,10 +109,15 @@ export type SandboxGuardrailBootstrapInput = {
     evidenceSchema?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     idempotencyKey?: string;
+    completionPreset?: string;
+    templateId?: string;
+    parameters?: Record<string, unknown>;
 };
 export type SandboxGuardrailEvidenceInput = {
     intentId: string;
     payload?: Record<string, unknown>;
+    /** Raw vendor response for vendor_pack presets; forwarded to Harbor schema drift checks. */
+    vendorPayload?: Record<string, unknown>;
     artifacts?: string[];
     operation?: string;
     requestedSpendCents?: number;
@@ -139,6 +148,13 @@ export type SandboxGuardrailEvidenceResult = {
     predicate_passed?: boolean | null;
     payload_digest?: string;
     artifacts_digest?: string;
+    schema_validation?: {
+        vendor_schema_ok: boolean;
+        canonical_schema_ok: boolean;
+        quality_fields_missing: string[];
+        pack_stale: boolean;
+        drift_kinds: string[];
+    };
     simulator_event?: unknown;
 };
 export declare const DEFAULT_PAYBOND_GATEWAY_BASE_URL = "https://api.paybond.ai";
@@ -770,9 +786,22 @@ export declare class PaybondSpendGuard {
     assertSpendAuthorized(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
     /** Finalizes scope reservations tied to an authorization decision after tool execution. */
     completeSpendAuthorization(decisionId: string, outcome: "consumed" | "released"): Promise<void>;
+    /**
+     * 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<TArgs extends unknown[], TResult>(input: PaybondSpendAuthorizationInput, handler: PaybondToolHandler<TArgs, TResult>): PaybondGuardedToolHandler<TArgs, TResult>;
 }
 export declare function authorizeSpend(source: PaybondSpendGuardInit | PaybondCapabilityBinding, input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
+/** Standalone alias for {@link PaybondSpendGuard.guardTool}. */
 export declare function guardTool<TArgs extends unknown[], TResult>(source: PaybondSpendGuardInit | PaybondCapabilityBinding, input: PaybondSpendAuthorizationInput, handler: PaybondToolHandler<TArgs, TResult>): PaybondGuardedToolHandler<TArgs, TResult>;
 export declare const paybondAgentToolSpendGuard: typeof guardTool;
 export declare const paybondRuntimeNeutralToolSpendGuard: typeof guardTool;
@@ -927,6 +956,13 @@ export declare class GatewayHarborClient {
     private headers;
     private fetchWithRetries;
     private postJSON;
+    private putJSON;
+    private requestJSON;
+    private getJSON;
+    /** Tenant-scoped Harbor operator intent detail (for attach run binding). */
+    getIntent(intentId: string): Promise<Record<string, unknown>>;
+    /** Gateway-backed middleware trace reporter for tenant console agent-runs view. */
+    createAgentRunTraceReporter(runId: string): GatewayAgentRunTraceReporter;
     private mutationHeaders;
     verifyCapability(input: PaybondSpendAuthorizationInput & {
         intentId: string;
@@ -949,6 +985,18 @@ export declare class GatewayHarborClient {
         decisionId: string;
         outcome: "consumed" | "released";
     }): Promise<void>;
+    /**
+     * Validate a paybond.policy.yaml document against the tenant Harbor registry
+     * (`POST /v1/policy/validate`).
+     */
+    validatePolicy(document: Record<string, unknown>, options?: PolicyRemoteValidateOptions): Promise<PolicyRemoteValidateResult>;
+    /**
+     * Resolve merged effective policy for a tenant overlay via
+     * `POST /v1/org-policies/{policy_id}/effective`.
+     */
+    resolvePolicyEffective(orgPolicyId: string, overlay: Record<string, unknown>, options?: {
+        currentDigest?: string;
+    }): Promise<PolicyEffectiveResolveResult>;
     createIntent(body: Record<string, unknown>, options: GatewayHarborMutationOptions): Promise<Record<string, unknown>>;
     fundIntent(intentId: string, options: GatewayHarborMutationOptions & {
         paymentSignature?: string;
@@ -1133,6 +1181,11 @@ export type PaybondSubmitEvidenceParams = Omit<SignPayeeEvidenceParams, "tenantI
     submittedAtRfc3339?: string;
     recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
 };
+/** Parameters for production intent create with a published managed-policy head (signing v5). */
+export type PaybondCreateIntentWithPolicyBindingParams = Omit<BuildSignedCreateIntentWithPolicyBindingParams, "tenantId" | "intentId"> & {
+    intentId?: string;
+    recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+};
 /**
  * Ergonomic intent helpers: principal-signed intent create, x402 funding, and payee-signed evidence.
  */
@@ -1143,6 +1196,12 @@ export declare 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.
      */
+    createWithPolicyBinding(params: PaybondCreateIntentWithPolicyBindingParams & {
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Build a principal-signed `POST /intents` body and submit it (raw predicate_dsl, signing v6).
+     */
     create(params: PaybondCreateIntentParams & {
         idempotencyKey?: string;
     }): Promise<Record<string, unknown>>;
@@ -1176,19 +1235,77 @@ export declare class Paybond {
     readonly a2a: GatewayA2AClient;
     readonly protocol: GatewayProtocolClient;
     readonly intents: PaybondIntents;
+    readonly agentRun: PaybondAgentRunFacade;
     private constructor();
     /** Open a tenant-bound hosted Paybond session from a service-account API key. */
     static open(init: PaybondOpenOptions): Promise<Paybond>;
     /** Reserved for future HTTP client cleanup; safe to call after work completes. */
     aclose(): Promise<void>;
     spendGuard(intentId: string, capabilityToken: string): PaybondSpendGuard;
+    /** Build a validated side-effecting tool registry for agent middleware. */
+    toolRegistry(config: PaybondToolRegistryConfig): PaybondToolRegistry;
     authorizeSpend(input: {
         intentId: string;
         token: string;
         operation: string;
         requestedSpendCents?: number;
     }): Promise<VerifyCapabilityResult>;
+    /** Policy-driven agent factory: load policy, bind a run, and wire framework tools. */
+    createGuardedAgent<TTools>(input: CreateGuardedAgentInput<TTools>): Promise<CreateGuardedAgentResult<TTools>>;
+    /** Alias for {@link Paybond.createGuardedAgent} matching runner helper naming. */
+    createGuardedAgentRunner<TTools>(input: CreateGuardedAgentInput<TTools>): Promise<CreateGuardedAgentResult<TTools>>;
+    /**
+     * One-liner instrumentation: load policy and return deferred tools or a bound runtime.
+     * Await for tools, or read `.binding`, `.bind()`, and `.status` on the result.
+     */
+    instrument<TTools>(input: PaybondInstrumentInput<TTools>, options?: PaybondWrapToolsOptions): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+    instrument<TAgent extends object>(agent: TAgent, options?: PaybondWrapToolsOptions & PaybondInstrumentAgentOptions): Promise<TAgent>;
+    /** Fluent builder: `paybond.policy("./paybond.policy.yaml").instrument(tools)`. */
+    policy(source: import("./policy/load.js").PaybondPolicyLoadSource | PaybondInlinePolicy): PaybondInstrumentBuilder;
+    /** Fluent builder for bundled vertical presets (`travel`, `shopping`, `saas`, `aws`). */
+    usePolicy(presetId: string): PaybondInstrumentBuilder;
+    instrumentLangGraph<TTools>(input: Omit<PaybondInstrumentInput<TTools>, "framework"> & {
+        tools: TTools;
+    }): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+    instrumentOpenAI<TTools>(input: Omit<PaybondInstrumentInput<TTools>, "framework"> & {
+        tools: TTools;
+    }): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+    instrumentVercel<TTools>(input: Omit<PaybondInstrumentInput<TTools>, "framework"> & {
+        tools: TTools;
+    }): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+    instrumentClaudeAgents<TTools>(input: Omit<PaybondInstrumentInput<TTools>, "framework"> & {
+        tools: TTools;
+    }): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+    /** Agent-agnostic instrumentation for MCP-style `{ name, execute }` tool hosts. */
+    instrumentMCP<TTools>(input: Omit<PaybondInstrumentInput<TTools>, "framework"> & {
+        tools: TTools;
+    }): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+    /**
+     * Opinionated quickstart: resolve named policy presets (for example `travel`) or file paths,
+     * then instrument tools for the selected framework.
+     */
+    agent<TTools>(input: PaybondAgentInput<TTools>): Promise<PaybondAgentResult<TTools>>;
+    /** Wrap tools for an existing bound run without reloading policy. */
+    wrapTools(run: import("./agent/run.js").PaybondAgentRun, tools: unknown, options?: PaybondWrapToolsOptions): unknown;
+    /**
+     * Compose bundled policy presets (`travel`, `shopping`, …) and guardrail layers.
+     * Example: `paybond.policyPresets.travel({ maxSpendUsd: 500 })`.
+     */
+    get policyPresets(): import("./policy/policy-api.js").PaybondPolicyPresets;
+    /**
+     * Bundled solution references (`travel`, `shopping`, …) with policy, smoke defaults,
+     * completion preset, and vendor pack metadata.
+     * Example: `paybond.solution.travel()`.
+     */
+    get solution(): import("./solutions/api.js").PaybondSolutionPresets;
 }
 export { normalizeJson, jsonValueDigest } from "./json-digest.js";
-export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, type BuildSignedCreateIntentParams, type SettlementRail, } from "./principal-intent.js";
+export { buildSignedCreateIntentBody, buildSignedCreateIntentBodyWithPolicyBinding, intentCreationSignBytesRaw, intentCreationSignBytesWithPolicyBinding, type BuildSignedCreateIntentParams, type BuildSignedCreateIntentWithPolicyBindingParams, type PolicyBindingRef, type PublishedPolicyHead, type SettlementRail, } from "./principal-intent.js";
 export { artifactsDigest, signPayeeEvidenceBinding, type SignPayeeEvidenceParams } from "./payee-evidence.js";
+export { AGENT_RECOGNITION_GATEWAY_VERIFIER_ID, AGENT_RECOGNITION_PROOF_KIND_V1, AGENT_RECOGNITION_PURPOSE_EVIDENCE_SUBMIT, newAgentRecognitionRequestEnvelope, signAgentRecognitionProofV1, signHarborEvidenceSubmitRecognitionProof, type SignAgentRecognitionProofV1Params, type SignedAgentRecognitionProofV1, } from "./agent-recognition.js";
+export { validateCompletionEvidence, type CompletionEvidenceValidationReport, } from "./completion-validate-evidence.js";
+export { completionSchemaDigestHex, computeVendorContractDigests, verifyVendorContract, verifyCatalogVendorContracts, type VendorContract, type VendorContractDigests, } from "./completion-contract-digest.js";
+export { contractSnapshotForPreset, mapVendorEvidenceToCanonical, resolveCompletionPreset, } from "./completion-resolve.js";
+export { PaybondAgentRun, PaybondAgentRunBindError, PaybondAgentRunFacade, PaybondEvidenceSubmitError, PaybondFrameworkAdapter, 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, type CreateGuardedAgentInput, type CreateGuardedAgentResult, type GuardedAgentFramework, type PaybondAgentHooks, type PaybondAgentInput, type PaybondAgentResult, type PaybondAgentRunBindInput, type PaybondAuthorizeToolCallInput, type PaybondEvidenceMapper, type PaybondGenericAgentConfig, type PaybondGenericToolCall, type PaybondGenericToolDefinition, type PaybondGenericWrappedToolDefinition, type PaybondInlinePolicy, type PaybondAgentInstrumentation, type PaybondInstrumentAgentOptions, type PaybondInstrumentBinding, type PaybondInstrumentContext, type PaybondInstrumentContextInput, type PaybondInstrumentContextProvider, type PaybondInstrumentInput, type PaybondInterceptEvidenceResult, type PaybondInterceptWrapExecuteInput, type PaybondInterceptWrapExecuteResult, type PaybondRunBinding, type PaybondRunBindingAttachInput, type PaybondRunBindingSandboxBootstrapInput, type PaybondRunGuard, type PaybondSideEffectingToolEntry, type PaybondSideEffectingToolPolicy, type PaybondSpendResolver, type PaybondToolCallContext, type PaybondToolInputGuardAllowDecision, type PaybondToolInputGuardApprovalRequiredDecision, type PaybondToolInputGuardDecision, type PaybondToolInputGuardDenyDecision, type PaybondToolInputGuardAdapter, type PaybondToolRegistryConfig, type PaybondToolResolution, type PaybondWrapToolsOptions, } from "./agent/index.js";
+export { PaybondPolicy, composePolicyLayers, composeBundledPresetDefault, domain, guardrails, paybondPolicyPresets, resolveComposedPresetDocument, type LayeredPolicyPresetId, type PaybondPolicyPresets, type PolicyGuardrailLayer, type PolicyPresetId, type VerticalPolicyOptions, } from "./policy/index.js";
+export { getSolutionSmokeDefaults, isKnownSolutionId, listSolutionIds, loadSolutionManifest, paybondSolutionPresets, type PaybondSolutionBundle, type PaybondSolutionPresets, type SolutionId, type SolutionManifest, type SolutionSmokeDefaults, } from "./solutions/index.js";