{"_id":"@agenticprimitives/surface-catalog","_rev":"4-36e5ea7b4a09ec703d573f545c6f0abc","name":"@agenticprimitives/surface-catalog","dist-tags":{"latest":"0.0.0-alpha.4"},"versions":{"0.0.0-alpha.1":{"name":"@agenticprimitives/surface-catalog","version":"0.0.0-alpha.1","keywords":["agentic","primitives","capability","mcp","a2a","openapi"],"license":"MIT","_id":"@agenticprimitives/surface-catalog@0.0.0-alpha.1","maintainers":[{"name":"richcanvas","email":"richardpedersen3@gmail.com"}],"homepage":"https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/surface-catalog","bugs":{"url":"https://github.com/agentictrustlabs/agenticprimitives/issues"},"dist":{"shasum":"45ce55530184e61b6ad1f16222df1113f9ba2c01","tarball":"https://registry.npmjs.org/@agenticprimitives/surface-catalog/-/surface-catalog-0.0.0-alpha.1.tgz","fileCount":24,"integrity":"sha512-Nb0NelVpqYDivO9Wuy2q3JO/dzycvixXnJVkSFOAM2Fr8huH/mxqOHRxB48wGB2pR37NUKGn9yT+pKypNzvpSw==","signatures":[{"sig":"MEUCICfmAnKtZ6eZ3VwAn4VGGK3vf3pQEELgnGN6idGX+HCUAiEA592d9ZDED7013av88Yf0GP/M5MZ+/FNxzDWzfBAKJ7c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46342},"main":"./dist/index.js","type":"module","_from":"file:agenticprimitives-surface-catalog-0.0.0-alpha.1.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","test:unit":"vitest run test/unit --passWithNoTests","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest"},"_npmUser":{"name":"richcanvas","email":"richardpedersen3@gmail.com"},"_resolved":"/tmp/a617ef3df8a9829ad2604ff7c1806156/agenticprimitives-surface-catalog-0.0.0-alpha.1.tgz","_integrity":"sha512-Nb0NelVpqYDivO9Wuy2q3JO/dzycvixXnJVkSFOAM2Fr8huH/mxqOHRxB48wGB2pR37NUKGn9yT+pKypNzvpSw==","repository":{"url":"git+https://github.com/agentictrustlabs/agenticprimitives.git","type":"git","directory":"packages/surface-catalog"},"_npmVersion":"11.16.0","description":"One SurfaceDescriptor per HTTP route / A2A skill / MCP tool, and the generators that derive A2A card skills, MCP tool declarations, OpenAPI 3.0, rate-limit profile bindings, and deployment preflight from it. Generic, transport-agnostic.","directories":{},"_nodeVersion":"24.12.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.8"},"_npmOperationalInternal":{"tmp":"tmp/surface-catalog_0.0.0-alpha.1_1782902638205_0.16757996145858978","host":"s3://npm-registry-packages-npm-production"}},"0.0.0-alpha.2":{"name":"@agenticprimitives/surface-catalog","version":"0.0.0-alpha.2","keywords":["agentic","primitives","capability","mcp","a2a","openapi"],"license":"MIT","_id":"@agenticprimitives/surface-catalog@0.0.0-alpha.2","maintainers":[{"name":"richcanvas","email":"richardpedersen3@gmail.com"}],"homepage":"https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/surface-catalog","bugs":{"url":"https://github.com/agentictrustlabs/agenticprimitives/issues"},"dist":{"shasum":"fd76bba3ef1519263d5158b858e3becc87005384","tarball":"https://registry.npmjs.org/@agenticprimitives/surface-catalog/-/surface-catalog-0.0.0-alpha.2.tgz","fileCount":28,"integrity":"sha512-lTx9ZQMJ7sTMjdBuiQHeNvbGz2IjljfXUqrVbKNuXXgCmhmaV0prvIa/CL8pbYvfsmc30ar2IqwfdZKZ3x5L8w==","signatures":[{"sig":"MEUCIHEudq99y6EUgScnH7k1jlXa4Fz7wtAgM9qel6NE9qM8AiEAogX2KrbmUA2Re4ex67P3hEnqgGs1g24Vy6qEh2mBw+E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":63534},"main":"./dist/index.js","type":"module","_from":"file:agenticprimitives-surface-catalog-0.0.0-alpha.2.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","test:unit":"vitest run test/unit --passWithNoTests","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:a38a9668-1bea-4e76-af11-9e16bec258a0"}},"_resolved":"/tmp/c57e09041008f37417abcf6d45a21e54/agenticprimitives-surface-catalog-0.0.0-alpha.2.tgz","_integrity":"sha512-lTx9ZQMJ7sTMjdBuiQHeNvbGz2IjljfXUqrVbKNuXXgCmhmaV0prvIa/CL8pbYvfsmc30ar2IqwfdZKZ3x5L8w==","repository":{"url":"git+https://github.com/agentictrustlabs/agenticprimitives.git","type":"git","directory":"packages/surface-catalog"},"_npmVersion":"11.16.0","description":"One SurfaceDescriptor per HTTP route / A2A skill / MCP tool, and the generators that derive A2A card skills, MCP tool declarations, OpenAPI 3.0, rate-limit profile bindings, and deployment preflight from it. Generic, transport-agnostic.","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.8"},"_npmOperationalInternal":{"tmp":"tmp/surface-catalog_0.0.0-alpha.2_1785727539369_0.5814722755930379","host":"s3://npm-registry-packages-npm-production"}},"0.0.0-alpha.3":{"name":"@agenticprimitives/surface-catalog","version":"0.0.0-alpha.3","keywords":["agentic","primitives","capability","mcp","a2a","openapi"],"license":"MIT","_id":"@agenticprimitives/surface-catalog@0.0.0-alpha.3","maintainers":[{"name":"richcanvas","email":"richardpedersen3@gmail.com"}],"homepage":"https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/surface-catalog","bugs":{"url":"https://github.com/agentictrustlabs/agenticprimitives/issues"},"dist":{"shasum":"7f6da87c5ae5799a16c23f3462b6c0ec18ffd264","tarball":"https://registry.npmjs.org/@agenticprimitives/surface-catalog/-/surface-catalog-0.0.0-alpha.3.tgz","fileCount":28,"integrity":"sha512-/un2QSykKnhynC7CCNKLpiIOJEpX08v5ff2svz7Jy1BsslIkYN3C0A6DoZQKRLeZtu/qvZe7z2FqVpSw5VO3Aw==","signatures":[{"sig":"MEUCIQCgFb8njgRfUbqaxOYQ+TVccZBXhrg+jjV3KgRW8PDmLwIgbxNJ135+SQHtOlbXSD3jbDWKuJvHKrzDkCcuKL4WYng=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCJbVAelfafoD4QqglcLNS4Ek5Pwp7R0mzBgfqScTJmnQIhAN7oo281TZBddneaLcCm+MMemKdUfmrMLEgWRKyhbrIL","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":71334},"main":"./dist/index.js","type":"module","_from":"file:agenticprimitives-surface-catalog-0.0.0-alpha.3.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","test:unit":"vitest run test/unit --passWithNoTests","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:a38a9668-1bea-4e76-af11-9e16bec258a0"}},"_resolved":"/tmp/f27186133f7d6f54b9a14d98e8b94610/agenticprimitives-surface-catalog-0.0.0-alpha.3.tgz","_integrity":"sha512-/un2QSykKnhynC7CCNKLpiIOJEpX08v5ff2svz7Jy1BsslIkYN3C0A6DoZQKRLeZtu/qvZe7z2FqVpSw5VO3Aw==","repository":{"url":"git+https://github.com/agentictrustlabs/agenticprimitives.git","type":"git","directory":"packages/surface-catalog"},"_npmVersion":"11.19.0","description":"One SurfaceDescriptor per HTTP route / A2A skill / MCP tool, and the generators that derive A2A card skills, MCP tool declarations, OpenAPI 3.0, rate-limit profile bindings, and deployment preflight from it. Generic, transport-agnostic.","directories":{},"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.8"},"_npmOperationalInternal":{"tmp":"tmp/surface-catalog_0.0.0-alpha.3_1789164305570_0.6427601380063914","host":"s3://npm-registry-packages-npm-production"}},"0.0.0-alpha.4":{"_id":"@agenticprimitives/surface-catalog@0.0.0-alpha.4","bugs":{"url":"https://github.com/agentictrustlabs/agenticprimitives/issues"},"dist":{"shasum":"956f69413b805c76ca1540564b772d74683b1d53","tarball":"https://registry.npmjs.org/@agenticprimitives/surface-catalog/-/surface-catalog-0.0.0-alpha.4.tgz","fileCount":28,"integrity":"sha512-aaYOdMW0SR6qgfsDpoOh/CAFqVWhV9y7YPkS5RcQaTyGnUCox60BbxmvjDQOT5j1R+VcC9pO5iMnzBabI5zo/A==","signatures":[{"sig":"MEUCIQCJy2Ms75Gzy5TPJyz2uA09TvNRgmaNKDoahresZpMI9AIgROO+59q3PvqEut9B0Np69pbSyxUKN5Ln7z8UruMlTI4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDun2sdh57Y03IPEcJnEccDmAa6Hw9GxG6JxQNvfOgaiAIhAPrnNVAqj8wJuuUZsI6bBGoEaLPRh2SaMQrpwoXLy98G"}],"unpackedSize":71334},"main":"./dist/index.js","name":"@agenticprimitives/surface-catalog","type":"module","_from":"file:agenticprimitives-surface-catalog-0.0.0-alpha.4.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"license":"MIT","scripts":{"test":"vitest run","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","test:unit":"vitest run test/unit --passWithNoTests","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest"},"version":"0.0.0-alpha.4","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:a38a9668-1bea-4e76-af11-9e16bec258a0"}},"homepage":"https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/surface-catalog","keywords":["agentic","primitives","capability","mcp","a2a","openapi"],"_resolved":"/tmp/d8fc04e8ee06cf92c63ce369e6daa687/agenticprimitives-surface-catalog-0.0.0-alpha.4.tgz","_integrity":"sha512-aaYOdMW0SR6qgfsDpoOh/CAFqVWhV9y7YPkS5RcQaTyGnUCox60BbxmvjDQOT5j1R+VcC9pO5iMnzBabI5zo/A==","repository":{"url":"git+https://github.com/agentictrustlabs/agenticprimitives.git","type":"git","directory":"packages/surface-catalog"},"_npmVersion":"11.19.0","description":"One SurfaceDescriptor per HTTP route / A2A skill / MCP tool, and the generators that derive A2A card skills, MCP tool declarations, OpenAPI 3.0, rate-limit profile bindings, and deployment preflight from it. Generic, transport-agnostic.","directories":{},"maintainers":[{"name":"richcanvas","email":"richardpedersen3@gmail.com"}],"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.8"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/surface-catalog_0.0.0-alpha.4_1789230641599_0.960358984590056"}}},"time":{"created":"2026-07-01T10:43:58.016Z","modified":"2026-09-12T16:30:41.859Z","0.0.0-alpha.1":"2026-07-01T10:43:58.368Z","0.0.0-alpha.2":"2026-08-03T03:25:39.553Z","0.0.0-alpha.3":"2026-09-11T22:05:05.653Z","0.0.0-alpha.4":"2026-09-12T16:30:41.681Z"},"bugs":{"url":"https://github.com/agentictrustlabs/agenticprimitives/issues"},"license":"MIT","homepage":"https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/surface-catalog","keywords":["agentic","primitives","capability","mcp","a2a","openapi"],"repository":{"url":"git+https://github.com/agentictrustlabs/agenticprimitives.git","type":"git","directory":"packages/surface-catalog"},"description":"One SurfaceDescriptor per HTTP route / A2A skill / MCP tool, and the generators that derive A2A card skills, MCP tool declarations, OpenAPI 3.0, rate-limit profile bindings, and deployment preflight from it. Generic, transport-agnostic.","maintainers":[{"name":"richcanvas","email":"richardpedersen3@gmail.com"}],"readme":"# @agenticprimitives/surface-catalog\n\nOne declaration for every HTTP route, A2A skill, and MCP tool — and the generators that derive the rest.\n\nInstead of hand-writing an A2A Agent Card here, MCP `declareTool` calls there, an OpenAPI doc somewhere\nelse, and rate-limit profiles in a fourth place — declare each capability **once** as a\n`SurfaceDescriptor`, then generate every downstream artifact from the catalog. Generic and\ntransport-agnostic: it carries no hostnames, no white-label/vertical content, and no chain types.\n\nSee [spec 288](../../specs/288-agentic-edge-admission-and-surface-catalog.md) §3 for the full design.\n\n## The descriptor\n\n```ts\nimport { defineSurface, type SurfaceDescriptor } from '@agenticprimitives/surface-catalog';\n\nconst getPii: SurfaceDescriptor = {\n  id: 'get_pii',\n  protocol: 'mcp',\n  description: \"Read the principal's PII record\",\n  inputSchema: { type: 'object', properties: { fields: { type: 'array', items: { type: 'string' } } } },\n  authorization: {\n    mode: 'agentic-delegation',\n    riskTier: 'high',\n    entitlement: { resource: 'person.pii', action: 'read', classification: 'pii.sensitive' },\n  },\n  operations: {\n    rateLimitProfile: 'sensitive-read-v1',\n    maxBodyBytes: 16_384,\n    timeoutMs: 10_000,\n    idempotency: 'safe',\n    cache: 'no-store',\n  },\n};\n\nconst registry = defineSurface([getPii]);\n```\n\nThe `authorization` block **references** the existing decision engines — `riskTier`/`requiredEnforcers`\nmap onto the `tool-policy` taxonomy, and `entitlement` onto the `entitlements` matcher. The registry is a\ncatalog that points at them; it never makes the authorization decision.\n\n## Generators\n\n```ts\nimport {\n  toMcpToolDeclaration,   // { name, classification } for tool-policy.declareTool\n  toMcpToolClassification,// the @sa-* object\n  toA2aSkill,             // an A2A card skill entry\n  toOpenApiDocument,      // OpenAPI 3.0 (what Cloudflare API Shield accepts)\n} from '@agenticprimitives/surface-catalog';\n\nconst decl = toMcpToolDeclaration(getPii);\n// → { name: 'get_pii', classification: { '@sa-tool': 'delegation-verified', '@sa-auth': 'session-token',\n//      '@sa-risk-tier': 'high', '@sa-rate-limit': 'sensitive-read-v1' } }\n\nconst openapi = toOpenApiDocument(registry, { title: 'Demo MCP', version: '1.0.0' });\n```\n\nOutputs are **structurally typed** (not hard-imported from `tool-policy`/`a2a`) so this package stays\ndependency-light; you feed the result to `declareTool`, your A2A card, or your OpenAPI host.\n\n## Deployment preflight\n\n```ts\nimport { runDeploymentPreflight, assertDeploymentPreflight, findCoverageGaps } from '@agenticprimitives/surface-catalog';\n\nassertDeploymentPreflight(registry);          // throws on any error finding\nrunDeploymentPreflight(registry);             // → PreflightFinding[] (errors + warnings)\nfindCoverageGaps(registry, liveMcpToolNames); // → ids with no descriptor\n```\n\nPreflight catches a mis-declared capability before it ships — e.g. an `agentic-delegation` capability\nwith no rate-limit profile, a `critical` capability that doesn't require on-chain acceptance, or a\n`public` capability marked high/critical risk.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}