@paybond/kit 0.12.4 → 0.12.6

package/dist/index.js

@@ -5,7 +5,7 @@
 import { buildSignedCreateIntentBody, buildSignedCreateIntentBodyWithPolicyBinding, } from "./principal-intent.js";
 import { signPayeeEvidenceBinding } from "./payee-evidence.js";
 import { PAYBOND_AGENT_RECEIPT_ATTESTATIONS_HEADER, PAYBOND_AGENT_RECEIPT_SOURCE_RUN_HEADER, } from "./agent-receipt.js";
-import { PaybondAgentRunFacade, createPaybondAgentCallable, PaybondInstrumentBuilder, createGuardedAgent, createGuardedAgentRunner, createPaybondAgent, createPaybondToolRegistry, instrumentPaybondAgent, instrumentPaybondClaudeAgents, instrumentPaybondLangGraph, instrumentPaybondMCP, instrumentPaybondOpenAI, instrumentPaybondVercel, resolveAgentPolicySource, wrapPaybondTools, } from "./agent/index.js";
+import { PaybondAgentRunFacade, createPaybondAgentCallable, PaybondInstrumentBuilder, createGuardedAgent, createGuardedAgentRunner, createPaybondAgent, createPaybondToolRegistry, instrumentPaybondAgent, instrumentPaybondClaudeAgents, instrumentPaybondLangGraph, instrumentPaybondMCP, instrumentPaybondOpenAI, instrumentPaybondGoogleAdk, instrumentPaybondVercel, resolveAgentPolicySource, wrapPaybondTools, } from "./agent/index.js";
 import { GatewayAgentRunTraceReporter, } from "./agent/gateway-trace-reporter.js";
 import { fetchWithGatewayRetries, gatewayRetryDelayMs, shouldRetryGatewayResponse, } from "./gateway-retry.js";
 import { PaybondAudit, PaybondAuditExports } from "./audit/index.js";
@@ -2562,6 +2562,9 @@ export class Paybond {
     instrumentOpenAI(input) {
         return instrumentPaybondOpenAI(this, input);
     }
+    instrumentGoogleAdk(input) {
+        return instrumentPaybondGoogleAdk(this, input);
+    }
     instrumentVercel(input) {
         return instrumentPaybondVercel(this, input);
     }
@@ -2604,12 +2607,17 @@ export { normalizeCommerceBinding, encodeCommerceBindingToStripeMetadata, decode
 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 { PaybondAgentRun, PaybondAgentRunBindError, PaybondAgentRunFacade, PaybondEvidenceSubmitError, PaybondToolInterceptor, PaybondToolRegistry, PaybondToolRegistryValidationError, PaybondUnregisteredSideEffectingToolError, buildAutoEvidencePayload, createGenericToolExecutor, createGuardedAgent, createGuardedAgentRunner, createPaybondAgent, createPaybondGenericAgentConfig, createPaybondGenericInputGuard, createPaybondToolRegistry, createToolInputGuardAdapter, instrumentPaybondAgent, instrumentPaybondClaudeAgents, instrumentPaybondLangGraph, instrumentPaybondMCP, instrumentPaybondOpenAI, instrumentPaybondGoogleAdk, instrumentPaybondVercel, paybondGenericToolExecutorAdapter, paybondToolInputGuardAdapter, resolveAgentPolicySource, toPaybondAgentResult, wrapPaybondTools, PaybondInstrumentBuilder, PaybondInstrumented, PaybondInstrumentRuntime, PaybondLazyContextError, PaybondUnboundContextError, discoverPolicyFromAgent, discoverToolNames, discoverToolsFromAgent, inlinePolicyToDocument, isInlinePolicy, isInstrumentableAgentObject, readPaybondAgentInstrumentation, } from "./agent/index.js";
 export { PaybondAudit, PaybondAuditExports, GatewayAuditExportsClient, parseAuditExportList, parseAuditExportJobGet, verifyAuditManifest, verifyAuditBundleLocal, } from "./audit/index.js";
 export { PaybondPolicy, composePolicyLayers, composeBundledPresetDefault, domain, guardrails, paybondPolicyPresets, resolveComposedPresetDocument, } from "./policy/index.js";
 export { getSolutionSmokeDefaults, isKnownSolutionId, listSolutionIds, loadSolutionManifest, paybondSolutionPresets, } from "./solutions/index.js";
 export { appendDirectHarborPaymentAuthorization, formatPaymentAuthorizationValue, PAYBOND_PAYMENT_AUTHORIZATION_HEADER, PAYMENT_TRANSPORT_RESPONSE_HEADERS, paymentAuthorizationGatewayHeader, readFundPaymentTransportHeaders, } from "./payment-transport.js";
-export { AGENT_RECEIPT_KIND_V1, AGENT_RECEIPT_SCHEMA_VERSION, AGENT_RECEIPT_SCOPE_ACTION, AGENT_RECEIPT_SCOPE_INTENT_TERMINAL, AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519, AGENT_RECEIPT_VERSION_V1, AGENT_RECEIPT_SIGNING_KEYS_WELL_KNOWN_PATH, AGENT_RECEIPT_WELL_KNOWN_PATH, PAYBOND_AGENT_RECEIPT_ATTESTATIONS_HEADER, PAYBOND_AGENT_RECEIPT_SOURCE_RUN_HEADER, actionReceiptId, attachOperatorAttestationV1, canonicalAgentReceiptBytes, configHashSha256Hex, promptHashSha256Hex, valueDigestSha256Hex, verifyAgentReceiptV1, verifyAgentReceiptV1FromJSON, } from "./agent-receipt.js";
+export { AGENT_RECEIPT_KIND_V1, AGENT_RECEIPT_SCHEMA_VERSION, AGENT_RECEIPT_SCOPE_ACTION, AGENT_RECEIPT_SCOPE_INTENT_TERMINAL, AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519, AGENT_RECEIPT_VERSION_V1, AGENT_RECEIPT_SIGNING_KEYS_WELL_KNOWN_PATH, AGENT_RECEIPT_WELL_KNOWN_PATH, AGENT_RECEIPT_VALIDITY_TIER_OPERATIONAL, AGENT_RECEIPT_VALIDITY_TIER_PRIMARY, AGENT_RECEIPT_VALIDITY_TIER_ATTESTED, EXTERNAL_ATTESTATION_KIND_AGENT_MANDATE_V1, SETTLEMENT_OUTCOME_SETTLED, SETTLEMENT_OUTCOME_PENDING_FINALITY, SETTLEMENT_OUTCOME_REVERSED, SETTLEMENT_OUTCOME_FAILED, PAYBOND_AGENT_RECEIPT_ATTESTATIONS_HEADER, PAYBOND_AGENT_RECEIPT_SOURCE_RUN_HEADER, actionReceiptId, achievedValidityTier, attachOperatorAttestationV1, canonicalAgentReceiptBytes, configHashSha256Hex, continuityFromPrior, promptHashSha256Hex, valueDigestSha256Hex, verifyAgentReceiptV1, verifyAgentReceiptV1FromJSON, verifyContinuityChain, } from "./agent-receipt.js";
+export { AGENT_RECEIPT_TRANSPARENCY_INCLUSION_PROOF_KIND_V1, AGENT_RECEIPT_TRANSPARENCY_SCHEMA_VERSION, AGENT_RECEIPT_TRANSPARENCY_STH_KIND_V1, merkleLeafHashRFC6962, merkleNodeHashRFC6962, verifyAgentReceiptInclusion, verifySignedTreeHeadV1, } from "./agent-receipt-inclusion.js";
+export { ACTA_AGENT_RECEIPT_TYPE, ACTA_SIGNATURE_ALG_EDDSA, projectActaDecisionFromAgentReceipt, projectAgentReceiptToActaDecisionReceipt, } from "./agent-receipt-acta.js";
+export { PEF_CANON_VERSION_JCS_RFC8785_V1, PEF_CLAIM_TYPE_AGENT_RECEIPT_V1, PEF_RECEIPT_FORMAT_AGENT_RECEIPT_V1, PEF_VERSION_V1, agentReceiptPefFrameId, agentReceiptPefPreimage, agentReceiptPefReceiptHash, buildAgentReceiptPefFrame, jcsCanonicalBytes, verifyAgentReceiptPefFrameId, } from "./agent-receipt-pef.js";
+export { AGENT_RECEIPT_SCITT_EXPORT_KIND_V1, AGENT_RECEIPT_SCITT_STATEMENT_KIND_V1, COSE_ALG_EDDSA, buildAgentReceiptScittExport, verifyAgentReceiptScittExport, } from "./agent-receipt-scitt.js";
+export { AGENT_RECEIPT_OWNER_DISCLOSURE_HPKE_SUITE, AGENT_RECEIPT_OWNER_DISCLOSURE_INFO, AGENT_RECEIPT_OWNER_DISCLOSURE_KIND_V1, AGENT_RECEIPT_OWNER_DISCLOSURE_PLAINTEXT_KIND_V1, AGENT_RECEIPT_OWNER_DISCLOSURE_SCHEMA_VERSION, decryptOwnerDisclosurePackage, deriveOwnerDisclosurePlaintext, encryptOwnerDisclosurePackage, generateX25519KeyPairHex, openHpkeBaseX25519Aes128Gcm, sealHpkeBaseX25519Aes128Gcm, } from "./agent-receipt-owner-disclosure.js";
 export { FORBIDDEN_AGENT_RECEIPT_FIELDS, parseAgentReceiptJSON, validateAgentReceiptJSON, } from "./agent-receipt-prevalidate.js";
 export { AGENT_RECEIPT_EXTERNAL_SOURCE_AP2, AGENT_RECEIPT_EXTERNAL_SOURCE_SEP2828, AGENT_RECEIPT_EXTERNAL_SOURCE_X402, partnerRecordDigestSha256Hex, protocolAuthorizationReceiptToExternalAttestations, protocolSettlementReceiptToExternalAttestations, resolveExternalAttestations, sep2828RecordsToExternalAttestations, signedMandateToExternalAttestations, x402ReceiptToExternalAttestations, } from "./agent-receipt-external-attestations.js";
 export { AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL, AGENT_RECEIPT_PDF_EXPORT_MANIFEST_KIND, AGENT_RECEIPT_PDF_EXPORT_MANIFEST_SCHEMA_VERSION, FORBIDDEN_PDF_EXPORT_MANIFEST_FIELDS, gateAgentReceiptPDFExport, parseAgentReceiptPDFExportManifestJSON, validateAgentReceiptPDFExportManifestJSON, } from "./agent-receipt-pdf-export.js";

package/dist/init.js

@@ -24,6 +24,7 @@ const AGENT_MIDDLEWARE_FRAMEWORKS = new Set([
     "vercel-ai",
     "mastra",
     "cloudflare-agents",
+    "google-adk",
     "mcp",
 ]);
 const AGENT_MIDDLEWARE_FRAMEWORK_ALIASES = {
@@ -233,6 +234,7 @@ function agentMiddlewareHeaderComments(framework) {
         "vercel-ai": "paybond agent demo vercel-ai smoke --operation travel.book_hotel --requested-spend-cents 20000 --evidence-preset cost_and_completion --format json",
         mastra: "paybond agent demo mastra smoke --operation travel.book_hotel --requested-spend-cents 20000 --evidence-preset cost_and_completion --format json",
         "cloudflare-agents": "paybond agent demo cloudflare-agents smoke --operation travel.book_hotel --requested-spend-cents 20000 --evidence-preset cost_and_completion --format json",
+        "google-adk": "paybond agent demo google-adk smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json",
         mcp: "paybond agent demo mcp smoke --operation travel.book_hotel --requested-spend-cents 20000 --evidence-preset cost_and_completion --format json",
     };
     return [
@@ -398,6 +400,33 @@ export function createGuardedMastraTools(run: PaybondAgentRun) {
     }),
   ];
   return createPaybondMastraConfig(run, tools).tools;
+}`;
+        case "google-adk":
+            return `import { FunctionTool } from "@google/adk";
+import { z } from "zod";
+import { createPaybondGoogleAdkConfig } from "@paybond/kit/google-adk";
+import type { PaybondAgentRun } from "@paybond/kit/agent";
+
+/** Wrap Google ADK FunctionTool definitions with Paybond middleware on \`execute\`. */
+export function createGuardedGoogleAdkTools(run: PaybondAgentRun) {
+  const tools = [
+    new FunctionTool({
+      name: "travel.book_hotel",
+      description: "Book a hotel room",
+      parameters: z.object({
+        city: z.string(),
+        estimatedPriceCents: z.number().int().nonnegative(),
+      }),
+      execute: async (args) => bookHotel(args),
+    }),
+    new FunctionTool({
+      name: "search.web",
+      description: "Search the web",
+      parameters: z.object({ query: z.string() }),
+      execute: async (args) => searchWeb(args),
+    }),
+  ];
+  return createPaybondGoogleAdkConfig(run, tools).tools;
 }`;
         case "cloudflare-agents":
             return `import { tool } from "ai";

package/dist/mcp-receipt-resource.js

@@ -26,7 +26,9 @@ export function agentReceiptResourceTemplateDefinition() {
         uriTemplate: MCP_AGENT_RECEIPT_RESOURCE_URI_TEMPLATE,
         name: "paybond_agent_receipt",
         title: "Paybond Agent Receipt",
-        description: "Signed paybond.agent_receipt_v1 JSON fetched tenant-bound from Gateway GET /protocol/v2/agent-receipts/{receipt_id}.",
+        description: "Agent-to-agent handoff of signed paybond.agent_receipt_v1 JSON. " +
+            "resources/read fetches tenant-bound GET /protocol/v2/agent-receipts/{receipt_id} " +
+            "and runs an operational-tier signature verify before returning contents.",
         mimeType: MCP_AGENT_RECEIPT_RESOURCE_MIME_TYPE,
     };
 }

package/dist/mcp-server.js

@@ -11,11 +11,11 @@ import { MCP_TOOL_ALLOWLIST_ENV, MCP_TOOL_POLICY_ENV, mergeMcpToolPolicy, parseM
 import { MCP_EVIDENCE_POLICY_ENV, McpEvidenceValidationGate, completionEvidenceValidationOk, extractHarborEvidenceValidationInput, extractSandboxGuardrailValidationInput, parseMcpEvidencePolicy, } from "./mcp-evidence-policy.js";
 import { McpCapabilityTokenCache, mcpToolStoresCapabilityToken, parseMcpCapabilityTokenCacheConfig, } from "./mcp-capability-token-cache.js";
 import { createMcpPolicyGatewayAdapter, McpPolicyReloadGate, parseMcpPolicyReloadConfig, } from "./mcp-policy-reload.js";
-import { verifyAgentReceiptV1FromJSON } from "./agent-receipt.js";
+import { AGENT_RECEIPT_KIND_V1, verifyAgentReceiptV1FromJSON, } from "./agent-receipt.js";
 import { agentReceiptResourceTemplateDefinition, agentReceiptResourceUri, MCP_AGENT_RECEIPT_RESOURCE_MIME_TYPE, parseAgentReceiptResourceUri, } from "./mcp-receipt-resource.js";
 import { DEFAULT_PAYBOND_GATEWAY_BASE_URL, GatewayFraudClient, GatewaySignalClient, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
-const SERVER_VERSION = "0.12.4";
+const SERVER_VERSION = "0.12.6";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const DEFAULT_RECOGNITION_VERIFIER_ID = "paybond-gateway";
@@ -63,14 +63,31 @@ const AUTHORIZE_SPEND_OUTPUT_PROPERTIES = {
 const TOOL_SELECTION_METADATA = {
     paybond_get_principal: {
         title: "Get Paybond Principal",
+        description: "Use this when you need to confirm which tenant-bound service-account principal the configured PAYBOND_API_KEY authenticates as " +
+            "(tenant_id, subject, and roles). Call early as a prerequisite before Harbor escrow, Signal reads, or other tenant-scoped tools when " +
+            "tenant identity is unknown. Not required before every later call once tenant_id is already known from a prior principal response or host config. " +
+            "Do not use this when you need Harbor intent escrow detail; use paybond_get_intent instead when you have an intent_id. " +
+            "Do not use this for A2A discovery; use paybond_get_a2a_agent_card instead. " +
+            "Makes one read-only external GET to the gateway principal endpoint; idempotent identity lookup with no side effects " +
+            "(no mutations, spend reservations, escrow changes, or ledger writes); auth or gateway failures surface as tool errors.",
         annotations: readOnlyToolAnnotations("Get Paybond Principal"),
         outputSchema: outputObjectSchema({
             tenant_id: {
                 type: "string",
                 description: "Tenant bound to the configured Paybond API key.",
+                examples: ["tenant-a"],
+            },
+            subject: {
+                type: "string",
+                description: "Service-account subject identifier echoed by the gateway for the authenticated API key (example: service-account-1).",
+                examples: ["service-account-1"],
+            },
+            roles: {
+                type: "array",
+                items: { type: "string" },
+                description: "RBAC roles granted to this principal for the authenticated tenant (example: [\"operator\"]).",
+                examples: [["operator"]],
             },
-            subject: { type: "string" },
-            roles: { type: "array", items: { type: "string" } },
         }),
     },
     paybond_verify_capability: {
@@ -330,12 +347,37 @@ const TOOL_SELECTION_METADATA = {
     },
     paybond_get_signed_portfolio_artifact: {
         title: "Get Signed Portfolio Artifact",
+        description: "Use this when you need a portable, tenant-scoped signed Signal portfolio snapshot (operator list plus Ed25519 signing material) " +
+            "for offline verifier checks or partner sharing—not a public leaderboard. " +
+            "Requires PAYBOND_API_KEY with Signal analytics read access. Omit score_version to use the gateway default current model (1.0). " +
+            "Do not use this for tenant-wide aggregates without signatures—call paybond_get_portfolio_summary—or for one operator's signed receipt—call " +
+            "paybond_get_reputation_receipt—or for one operator's fraud review posture—call paybond_get_fraud_assessment. " +
+            "Idempotent read with no side effects; auth, RBAC, feature, or gateway failures surface as tool errors.",
         annotations: readOnlyToolAnnotations("Get Signed Portfolio Artifact"),
         outputSchema: outputObjectSchema({
-            tenant_id: { type: "string" },
-            kind: { type: "string" },
-            signature_hex: { type: "string" },
-            checkpoint_last_ledger_seq: { type: "integer" },
+            kind: {
+                type: "string",
+                description: "Artifact kind identifier (currently paybond.signal.portfolio_snapshot).",
+                examples: ["paybond.signal.portfolio_snapshot"],
+            },
+            tenant_id: {
+                type: "string",
+                description: "Tenant echoed by the gateway for the authenticated API key (example: tenant-a). Never invent tenant identifiers.",
+                examples: ["tenant-a"],
+            },
+            score_model_version: {
+                type: "string",
+                description: "Score model version used for the artifact (echoes the requested score_version or the gateway default 1.0).",
+                examples: ["1.0"],
+            },
+            checkpoint_last_ledger_seq: {
+                type: "integer",
+                description: "Last ledger sequence included in the tenant Signal checkpoint for this artifact.",
+            },
+            signature_hex: {
+                type: "string",
+                description: "Ed25519 signature hex over the canonical portfolio artifact payload.",
+            },
         }),
     },
     paybond_get_fraud_assessment: {
@@ -508,6 +550,65 @@ const TOOL_SELECTION_METADATA = {
             intent_id: { type: "string" },
         }, ["tenant_id", "receipt_id"]),
     },
+    paybond_get_agent_receipt_v1: {
+        title: "Get Agent Receipt",
+        description: "Use this when you need the signed paybond.agent_receipt_v1 JSON for one receipt_id " +
+            "(SHA-256 action id or intent-terminal UUID) via tenant-bound Gateway GET. " +
+            "Do not use this for protocol settlement receipts—call paybond_get_settlement_receipt_v1. " +
+            "For agent-to-agent handoff without embedding JSON in prompts, prefer the MCP resource " +
+            "paybond://receipt/{receipt_id} (resources/read verifies at the operational tier). " +
+            "Validity tiers beyond operational, continuity-chain, inclusion proofs, owner disclosure, " +
+            "and ACTA/PEF/SCITT adapters are Kit/CLI/Gateway auditor surfaces—not this tool's job. " +
+            "Read-only and side-effect free.",
+        annotations: readOnlyToolAnnotations("Get Agent Receipt"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string" },
+            receipt_id: { type: "string" },
+            kind: { type: "string" },
+        }, ["tenant_id", "receipt_id"]),
+    },
+    paybond_verify_agent_receipt_v1: {
+        title: "Verify Agent Receipt",
+        description: "Use this when you already have a signed paybond.agent_receipt_v1 JSON object and need an " +
+            "offline operational-tier (default) Ed25519 signature check—schema, digest, and Gateway " +
+            "signature—matching resources/read on paybond://receipt/{receipt_id}. " +
+            "Optional validity_tier=primary|attested raises the bar (payee digest / operator attestation). " +
+            "Do not use this for protocol authorization/settlement receipts—call paybond_verify_protocol_receipt_v1. " +
+            "Continuity-chain audits, inclusion proofs, owner disclosure, and ACTA/PEF/SCITT are Kit/CLI/Gateway " +
+            "auditor surfaces. Read-only and side-effect free: success returns valid=true with kind, receipt_id, " +
+            "tenant_id, and the normalized receipt; failures raise a clear verification error.",
+        annotations: readOnlyToolAnnotations("Verify Agent Receipt"),
+        outputSchema: outputObjectSchema({
+            valid: {
+                type: "boolean",
+                description: "True when operational (or requested) validity checks passed. Example: true.",
+                examples: [true],
+            },
+            kind: {
+                type: "string",
+                description: "Verified receipt kind (paybond.agent_receipt_v1).",
+                examples: ["paybond.agent_receipt_v1"],
+            },
+            receipt_id: {
+                type: "string",
+                description: "Canonical receipt identifier from the verified receipt.",
+            },
+            tenant_id: {
+                type: "string",
+                description: "Tenant id embedded in the verified receipt (not invented by the caller).",
+            },
+            validity_tier: {
+                type: "string",
+                description: "Requested validity tier used for this verify (operational, primary, or attested).",
+                examples: ["operational", "primary", "attested"],
+            },
+            receipt: {
+                type: "object",
+                additionalProperties: true,
+                description: "Normalized verified paybond.agent_receipt_v1 object.",
+            },
+        }),
+    },
     paybond_verify_protocol_receipt_v1: {
         title: "Verify Protocol Receipt",
         description: "Use this when you already have a signed protocol-v2 authorization or settlement receipt JSON object and need offline Ed25519 verification (structure, message digest, and signature) through the gateway. " +
@@ -1508,7 +1609,13 @@ export class PaybondMCPServer {
         const tools = [
             {
                 name: "paybond_get_principal",
-                description: "Resolve the tenant-bound Paybond principal behind the configured service-account API key.",
+                description: "Use this when you need to confirm which tenant-bound service-account principal the configured PAYBOND_API_KEY authenticates as " +
+                    "(tenant_id, subject, and roles). Call early as a prerequisite before Harbor escrow, Signal reads, or other tenant-scoped tools when " +
+                    "tenant identity is unknown. Not required before every later call once tenant_id is already known from a prior principal response or host config. " +
+                    "Do not use this when you need Harbor intent escrow detail; use paybond_get_intent instead when you have an intent_id. " +
+                    "Do not use this for A2A discovery; use paybond_get_a2a_agent_card instead. " +
+                    "Makes one read-only external GET to the gateway principal endpoint; idempotent identity lookup with no side effects " +
+                    "(no mutations, spend reservations, escrow changes, or ledger writes); auth or gateway failures surface as tool errors.",
                 inputSchema: emptyObjectSchema(),
                 call: async () => this.runtime.principal(),
             },
@@ -1782,7 +1889,11 @@ export class PaybondMCPServer {
                 name: "paybond_get_signed_portfolio_artifact",
                 description: "Fetch the tenant-scoped signed Signal portfolio artifact for portable verifier and partner sharing.",
                 inputSchema: objectSchema({
-                    score_version: { type: "string" },
+                    score_version: {
+                        type: "string",
+                        description: "Optional Signal score model version to query. Omit to use the gateway default current model (1.0). Example: 1.0.",
+                        examples: ["1.0"],
+                    },
                 }),
                 call: async (args) => (await this.runtime.signal()).getSignedPortfolioArtifact(optionalString(args.score_version)),
             },
@@ -1896,6 +2007,61 @@ export class PaybondMCPServer {
                 }, ["receipt_id"]),
                 call: async (args) => this.runtime.getSettlementReceiptV1(uuidArg(args.receipt_id, "receipt_id")),
             },
+            {
+                name: "paybond_get_agent_receipt_v1",
+                description: "Fetch the signed paybond.agent_receipt_v1 for one receipt_id.",
+                inputSchema: objectSchema({
+                    receipt_id: {
+                        type: "string",
+                        description: "Agent receipt id: lowercase SHA-256 hex (action scope) or canonical UUID (intent_terminal). " +
+                            "Must belong to the authenticated tenant; do not invent tenant identifiers.",
+                    },
+                }, ["receipt_id"]),
+                call: async (args) => this.runtime.getAgentReceiptV1(agentReceiptIdArg(args.receipt_id)),
+            },
+            {
+                name: "paybond_verify_agent_receipt_v1",
+                description: "Verify a signed paybond.agent_receipt_v1 offline (operational tier by default).",
+                inputSchema: objectSchema({
+                    receipt: {
+                        type: "object",
+                        additionalProperties: true,
+                        description: "Complete signed paybond.agent_receipt_v1 object (not a receipt_id string). " +
+                            "Obtain from paybond_get_agent_receipt_v1, paybond://receipt/{receipt_id}, " +
+                            "audit export (agent_receipts/{id}.json; PEF companions may also appear as *.pef.json), " +
+                            "or partner handoff—do not invent digests or signatures.",
+                    },
+                    validity_tier: {
+                        type: "string",
+                        description: "Optional validity bar: operational (default), primary, or attested. " +
+                            "Higher tiers are auditor-oriented; MCP handoff only requires operational.",
+                        enum: ["operational", "primary", "attested"],
+                    },
+                }, ["receipt"]),
+                call: async (args) => {
+                    const receipt = ensureObject(args.receipt, "receipt");
+                    const validityTier = args.validity_tier === undefined
+                        ? "operational"
+                        : stringArg(args.validity_tier, "validity_tier").toLowerCase();
+                    let verified;
+                    try {
+                        verified = await verifyAgentReceiptV1FromJSON(receipt, {
+                            requiredValidityTier: validityTier,
+                        });
+                    }
+                    catch (err) {
+                        throw new Error(`agent receipt verification failed: ${formatError(err)}`);
+                    }
+                    return {
+                        valid: true,
+                        kind: AGENT_RECEIPT_KIND_V1,
+                        receipt_id: verified.receipt_id,
+                        tenant_id: verified.tenant_id,
+                        validity_tier: validityTier,
+                        receipt: verified,
+                    };
+                },
+            },
             {
                 name: "paybond_verify_protocol_receipt_v1",
                 description: "Verify a signed protocol-v2 authorization or settlement receipt through the gateway.",
@@ -2186,6 +2352,12 @@ function uuidArg(value, field) {
     }
     return raw;
 }
+/** Accept action-scope SHA-256 hex or intent-terminal UUID receipt ids. */
+function agentReceiptIdArg(value) {
+    const raw = stringArg(value, "receipt_id").toLowerCase();
+    // Validates via URI helper shared with resources/read.
+    return parseAgentReceiptResourceUri(`paybond://receipt/${raw}`);
+}
 function stringArrayArg(value, field) {
     if (!Array.isArray(value)) {
         throw new Error(`${field} must be an array`);

package/dist/policy/adapter-options.d.ts

@@ -0,0 +1,9 @@
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+import type { PaybondVercelAgentConfigOptions } from "../vercel-ai/config.js";
+/** Adapter options derived from a flat effective `paybond.policy.yaml` document. */
+export type PaybondPolicyAdapterOptions = Pick<PaybondVercelAgentConfigOptions, "denyProviderExecutedTools">;
+/**
+ * Map policy `adapter.deny_provider_executed_tools` to Vercel AI / Cloudflare Agents options.
+ * Returns an empty object when the policy leaves the flag unset (adapter default applies).
+ */
+export declare function policyToAdapterOptions(document: PaybondPolicyDocumentV1): PaybondPolicyAdapterOptions;

package/dist/policy/adapter-options.js

@@ -0,0 +1,11 @@
+/**
+ * Map policy `adapter.deny_provider_executed_tools` to Vercel AI / Cloudflare Agents options.
+ * Returns an empty object when the policy leaves the flag unset (adapter default applies).
+ */
+export function policyToAdapterOptions(document) {
+    const deny = document.adapter?.deny_provider_executed_tools;
+    if (deny !== true) {
+        return {};
+    }
+    return { denyProviderExecutedTools: true };
+}

package/dist/policy/index.d.ts

@@ -1,4 +1,5 @@
 export { canonicalPolicyDocumentDigest, policyDocumentToDict, policyVersionLabel, } from "./digest.js";
+export { policyToAdapterOptions, type PaybondPolicyAdapterOptions, } from "./adapter-options.js";
 export { PaybondPolicy, type PaybondPolicyLoadSource, type PaybondPolicyLoadEffectiveResult } from "./load.js";
 export { isKnownPolicyPresetId, isLayeredPolicyPresetId, listPolicyPresetIds, readPolicyPresetYaml, resolveComposedPresetDocument, resolvePolicyPresetPath, type LayeredPolicyPresetId, type PolicyPresetId, } from "./presets.js";
 export { assertLayeredPresetMatchesFlat, bundledDefaultGuardrails, composeBundledPresetDefault, composeLayeredPolicyPresetDocument, composePolicyLayers, composePolicyPresetLayers, isLayeredPolicyPreset, LAYERED_POLICY_PRESET_IDS, } from "./compose.js";

package/dist/policy/index.js

@@ -1,4 +1,5 @@
 export { canonicalPolicyDocumentDigest, policyDocumentToDict, policyVersionLabel, } from "./digest.js";
+export { policyToAdapterOptions, } from "./adapter-options.js";
 export { PaybondPolicy } from "./load.js";
 export { isKnownPolicyPresetId, isLayeredPolicyPresetId, listPolicyPresetIds, readPolicyPresetYaml, resolveComposedPresetDocument, resolvePolicyPresetPath, } from "./presets.js";
 export { assertLayeredPresetMatchesFlat, bundledDefaultGuardrails, composeBundledPresetDefault, composeLayeredPolicyPresetDocument, composePolicyLayers, composePolicyPresetLayers, isLayeredPolicyPreset, LAYERED_POLICY_PRESET_IDS, } from "./compose.js";

package/dist/policy/load.d.ts

@@ -3,6 +3,7 @@ import { type PaybondPolicyIntentCreateInput, type PaybondPolicyIntentCreateOver
 import { type PolicyMergeOptions, type PolicyMergeResult } from "./merge.js";
 import { type PaybondPolicyDocument, type PaybondPolicyDocumentV1 } from "./schema.js";
 import { type PaybondPolicySandboxBootstrapOptions } from "./sandbox-bootstrap.js";
+import { type PaybondPolicyAdapterOptions } from "./adapter-options.js";
 import { type PolicyValidatorOptions, type PolicyValidatorResult } from "./validate.js";
 import { type PolicyRemoteValidateClient, type PolicyRemoteValidateOptions, type PolicyRemoteValidateResult } from "./validate-remote.js";
 import { type PolicyEffectiveResolveClient } from "./load-effective.js";
@@ -31,6 +32,12 @@ export declare class PaybondPolicy {
     get defaultDeny(): boolean;
     /** Optional intent section from the policy file. */
     get intent(): PaybondPolicyDocumentV1["intent"];
+    /** Optional adapter section from the policy file. */
+    get adapter(): PaybondPolicyDocumentV1["adapter"];
+    /** Whether provider-executed AI SDK tools should fail closed (Vercel AI / Cloudflare Agents). */
+    get denyProviderExecutedTools(): boolean;
+    /** Map policy adapter settings to framework runner options. */
+    toAdapterOptions(): PaybondPolicyAdapterOptions;
     /**
      * Load and validate a policy from a file path or pre-parsed document object.
      * File paths accept JSON (`.json`) or YAML (`.yaml` / `.yml`).

package/dist/policy/load.js

@@ -6,6 +6,7 @@ import { parsePolicyDocumentText } from "./parse-text.js";
 import { policyToToolRegistry } from "./registry.js";
 import { isPaybondPolicyDocumentV2, isPaybondPolicyOverlay, parsePaybondPolicyDocument, parsePaybondPolicyDocumentV1, } from "./schema.js";
 import { policySandboxBootstrap, } from "./sandbox-bootstrap.js";
+import { policyToAdapterOptions } from "./adapter-options.js";
 import { PolicyValidator } from "./validate.js";
 import { validatePolicyRemote, validatePolicyPayloadRemote, } from "./validate-remote.js";
 import { resolvePolicyEffectiveRemote, } from "./load-effective.js";
@@ -32,6 +33,18 @@ export class PaybondPolicy {
     get intent() {
         return this.document.intent;
     }
+    /** Optional adapter section from the policy file. */
+    get adapter() {
+        return this.document.adapter;
+    }
+    /** Whether provider-executed AI SDK tools should fail closed (Vercel AI / Cloudflare Agents). */
+    get denyProviderExecutedTools() {
+        return this.document.adapter?.deny_provider_executed_tools === true;
+    }
+    /** Map policy adapter settings to framework runner options. */
+    toAdapterOptions() {
+        return policyToAdapterOptions(this.document);
+    }
     /**
      * Load and validate a policy from a file path or pre-parsed document object.
      * File paths accept JSON (`.json`) or YAML (`.yaml` / `.yml`).

package/dist/policy/merge.js

@@ -177,6 +177,30 @@ function intersectAllowedTools(orgAllowed, tenantAllowed, denied, report) {
     }
     return intersection;
 }
+function mergeAdapterSection(base, overlay, override, denied, report) {
+    const values = [
+        base?.deny_provider_executed_tools,
+        overlay?.deny_provider_executed_tools,
+        override?.deny_provider_executed_tools,
+    ];
+    if (values.every((value) => value === undefined)) {
+        return undefined;
+    }
+    if (base?.deny_provider_executed_tools === true &&
+        (overlay?.deny_provider_executed_tools === false ||
+            override?.deny_provider_executed_tools === false)) {
+        denied.push({
+            path: "adapter.deny_provider_executed_tools",
+            code: "policy.cannot_relax_provider_executed_deny",
+            message: "tenant cannot disable org-required deny_provider_executed_tools",
+        });
+    }
+    if (override?.deny_provider_executed_tools !== undefined) {
+        report.overrides_applied.push("overrides.adapter.deny_provider_executed_tools");
+    }
+    const deny = mergeStricterDefaultDeny(...values);
+    return deny ? { deny_provider_executed_tools: true } : { deny_provider_executed_tools: false };
+}
 function baseDocumentToEffectiveV1(document) {
     return {
         version: PAYBOND_POLICY_SCHEMA_VERSION,
@@ -184,6 +208,7 @@ function baseDocumentToEffectiveV1(document) {
         default_deny: document.default_deny,
         tools: Object.fromEntries(Object.entries(document.tools).map(([toolName, entry]) => [toolName, cloneToolEntry(entry)])),
         intent: document.intent ? structuredClone(document.intent) : undefined,
+        adapter: document.adapter ? structuredClone(document.adapter) : undefined,
     };
 }
 function assertOverlay(document) {
@@ -258,6 +283,7 @@ export function mergePaybondPolicies(base, overlay, options = {}) {
             effective.intent = structuredClone(base.intent);
         }
     }
+    effective.adapter = mergeAdapterSection(base.adapter, overlay.adapter, overlay.overrides?.adapter, denied, report);
     if (options.approvedEvidencePresets) {
         const approved = new Set(options.approvedEvidencePresets);
         for (const [toolName, entry] of Object.entries(effective.tools)) {

package/dist/policy/schema.d.ts

@@ -44,6 +44,12 @@ declare const policyIntentSchema: z.ZodObject<{
     }, z.core.$loose>>;
     allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
+declare const policyAdapterSchema: z.ZodObject<{
+    deny_provider_executed_tools: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+declare const policyAdapterOverrideSchema: z.ZodObject<{
+    deny_provider_executed_tools: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
 declare const policyIntentOverrideSchema: z.ZodObject<{
     policy_binding: z.ZodOptional<z.ZodObject<{
         template_id: z.ZodOptional<z.ZodString>;
@@ -84,6 +90,9 @@ declare const policyOverridesSchema: z.ZodObject<{
         }, z.core.$loose>>;
         allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    adapter: z.ZodOptional<z.ZodObject<{
+        deny_provider_executed_tools: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const paybondPolicyDocumentV1Schema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -109,6 +118,9 @@ export declare const paybondPolicyDocumentV1Schema: z.ZodObject<{
         }, z.core.$loose>>;
         allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    adapter: z.ZodOptional<z.ZodObject<{
+        deny_provider_executed_tools: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const paybondPolicyDocumentV2Schema: z.ZodObject<{
     version: z.ZodLiteral<2>;
@@ -142,6 +154,9 @@ export declare const paybondPolicyDocumentV2Schema: z.ZodObject<{
             }, z.core.$loose>>;
             allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
+        adapter: z.ZodOptional<z.ZodObject<{
+            deny_provider_executed_tools: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     tools: z.ZodRecord<z.ZodString, z.ZodObject<{
         side_effecting: z.ZodBoolean;
@@ -163,6 +178,9 @@ export declare const paybondPolicyDocumentV2Schema: z.ZodObject<{
         }, z.core.$loose>>;
         allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    adapter: z.ZodOptional<z.ZodObject<{
+        deny_provider_executed_tools: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type PaybondPolicyToolEntry = z.infer<typeof policyToolEntrySchema>;
 export type PaybondPolicyToolOverrideEntry = z.infer<typeof policyToolOverrideEntrySchema>;
@@ -170,6 +188,8 @@ export type PaybondPolicyBinding = z.infer<typeof policyBindingSchema>;
 export type PaybondPolicyBindingOverride = z.infer<typeof policyBindingOverrideSchema>;
 export type PaybondPolicyBudget = z.infer<typeof policyBudgetSchema>;
 export type PaybondPolicyIntentSection = z.infer<typeof policyIntentSchema>;
+export type PaybondPolicyAdapterSection = z.infer<typeof policyAdapterSchema>;
+export type PaybondPolicyAdapterOverrideSection = z.infer<typeof policyAdapterOverrideSchema>;
 export type PaybondPolicyIntentOverrideSection = z.infer<typeof policyIntentOverrideSchema>;
 export type PaybondPolicyExtends = z.infer<typeof policyExtendsSchema>;
 export type PaybondPolicyOverrides = z.infer<typeof policyOverridesSchema>;

package/dist/policy/schema.js

@@ -114,6 +114,34 @@ const policyIntentSchema = z
     allowed_tools: z.array(toolNameSchema).optional(),
 })
     .strict();
+const policyAdapterSchema = z
+    .object({
+    deny_provider_executed_tools: z.boolean().optional(),
+})
+    .strict()
+    .superRefine((adapter, ctx) => {
+    if (Object.keys(adapter).length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: [],
+            message: "adapter must set at least one field",
+        });
+    }
+});
+const policyAdapterOverrideSchema = z
+    .object({
+    deny_provider_executed_tools: z.boolean().optional(),
+})
+    .strict()
+    .superRefine((adapter, ctx) => {
+    if (Object.keys(adapter).length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: [],
+            message: "adapter override must set at least one field",
+        });
+    }
+});
 const policyIntentOverrideSchema = z
     .object({
     policy_binding: policyBindingOverrideSchema.optional(),
@@ -145,16 +173,18 @@ const policyOverridesSchema = z
     default_deny: z.boolean().optional(),
     tools: z.record(toolNameSchema, policyToolOverrideEntrySchema).optional(),
     intent: policyIntentOverrideSchema.optional(),
+    adapter: policyAdapterOverrideSchema.optional(),
 })
     .strict()
     .superRefine((overrides, ctx) => {
     if (overrides.default_deny === undefined &&
         !overrides.tools &&
-        !overrides.intent) {
+        !overrides.intent &&
+        !overrides.adapter) {
         ctx.addIssue({
             code: "custom",
             path: [],
-            message: "overrides must set default_deny, tools, and/or intent",
+            message: "overrides must set default_deny, tools, intent, and/or adapter",
         });
     }
 });
@@ -169,6 +199,7 @@ export const paybondPolicyDocumentV1Schema = z
         message: "tools must declare at least one entry",
     }),
     intent: policyIntentSchema.optional(),
+    adapter: policyAdapterSchema.optional(),
 })
     .strict();
 export const paybondPolicyDocumentV2Schema = z
@@ -180,6 +211,7 @@ export const paybondPolicyDocumentV2Schema = z
     overrides: policyOverridesSchema.optional(),
     tools: z.record(toolNameSchema, policyToolEntrySchema),
     intent: policyIntentSchema.optional(),
+    adapter: policyAdapterSchema.optional(),
 })
     .strict()
     .superRefine((document, ctx) => {