{"_id":"@aevr/agents-openapi","_rev":"4-c6be787c68ed2aaf2df36bfd2cf7bf56","name":"@aevr/agents-openapi","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@aevr/agents-openapi","version":"0.1.0","keywords":["agents","autonomous-agents","openapi","typescript"],"license":"MIT","_id":"@aevr/agents-openapi@0.1.0","maintainers":[{"name":"miracleio","email":"miracleficient@gmail.com"}],"homepage":"https://github.com/miracleonyenma/proxmox-management/tree/main/packages/agents-openapi#readme","bugs":{"url":"https://github.com/miracleonyenma/proxmox-management/issues"},"dist":{"shasum":"68588299fc6888dbae8085316752967c65371db4","tarball":"https://registry.npmjs.org/@aevr/agents-openapi/-/agents-openapi-0.1.0.tgz","fileCount":43,"integrity":"sha512-dA+qgD6zxebMQwRJsO8pKlW3JLK2JuBz+AF91ysDmBkAqQnMQPAuu0lwgVM6RTY50+NHcvKXOPNko3bONY8aPg==","signatures":[{"sig":"MEQCIAqqilDmdbd+SzIFGsukfhX3RNQ4EZOwv/P9vUMyl9nHAiA8Y0R+uhOXl2OYYP+6ULBiy3y+5gMAUy5DgU839uD92g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":281506},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"tsx --test src/*.test.ts src/**/*.test.ts","build":"tsc -p .","release":"standard-version --tag-prefix agents-openapi@v","typecheck":"tsc --noEmit","release:major":"standard-version --release-as major --tag-prefix agents-openapi@v","release:minor":"standard-version --release-as minor --tag-prefix agents-openapi@v","release:patch":"standard-version --release-as patch --tag-prefix agents-openapi@v","verify:exports":"node scripts/check-exports.mjs","verify:package":"node scripts/verify-package.mjs"},"_npmUser":{"name":"miracleio","email":"miracleficient@gmail.com"},"repository":{"url":"git+https://github.com/miracleonyenma/proxmox-management.git","type":"git","directory":"packages/agents-openapi"},"description":"OpenAPI 3.1 capability generation and authenticated HTTP execution for @aevr/agents.","directories":{},"sideEffects":false,"_nodeVersion":"24.19.0","dependencies":{"ajv":"^8.20.0","yaml":"^2.9.0","ajv-formats":"^3.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","typescript":"^5.7.2","@types/node":"20.19.43","@aevr/agents":"0.2.0","standard-version":"^9.5.0"},"peerDependencies":{"@aevr/agents":"^0.2.0"},"_npmOperationalInternal":{"tmp":"tmp/agents-openapi_0.1.0_1787413357464_0.061786004320326215","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aevr/agents-openapi","version":"0.1.1","keywords":["agents","autonomous-agents","openapi","typescript"],"license":"MIT","_id":"@aevr/agents-openapi@0.1.1","maintainers":[{"name":"miracleio","email":"miracleficient@gmail.com"}],"homepage":"https://github.com/miracleonyenma/proxmox-management/tree/main/packages/agents-openapi#readme","bugs":{"url":"https://github.com/miracleonyenma/proxmox-management/issues"},"bin":{"aevr-agents-openapi":"./dist/cli.js"},"dist":{"shasum":"2fd7550148d10533700d4fb6edf0b67730933ba7","tarball":"https://registry.npmjs.org/@aevr/agents-openapi/-/agents-openapi-0.1.1.tgz","fileCount":47,"integrity":"sha512-p3YHH8U3dzZtzJVJdRRY1NdNF2zAaGBnaB9L4yUyQ9OZbBfxKFp8E53rXqvg0kaYLuv+Xyjj5upWLGoozoiGQA==","signatures":[{"sig":"MEUCIG9j5PSEWUaUqG2Ru+adBJiIqsynCMCleOy+/EpcDhOFAiEApoY8JGmlSq9Me4Gc+pY6yBj400wVXTbHEbmcZu7J5P0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":291032},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"tsx --test src/*.test.ts src/**/*.test.ts","build":"tsc -p . && node scripts/make-cli-executable.mjs","release":"standard-version --tag-prefix agents-openapi@v","typecheck":"tsc --noEmit","release:major":"standard-version --release-as major --tag-prefix agents-openapi@v","release:minor":"standard-version --release-as minor --tag-prefix agents-openapi@v","release:patch":"standard-version --release-as patch --tag-prefix agents-openapi@v","verify:exports":"node scripts/check-exports.mjs","verify:package":"node scripts/verify-package.mjs"},"_npmUser":{"name":"miracleio","email":"miracleficient@gmail.com"},"repository":{"url":"git+https://github.com/miracleonyenma/proxmox-management.git","type":"git","directory":"packages/agents-openapi"},"description":"OpenAPI 3.1 capability generation and authenticated HTTP execution for @aevr/agents.","directories":{},"sideEffects":false,"_nodeVersion":"24.19.0","dependencies":{"ajv":"^8.20.0","yaml":"^2.9.0","ajv-formats":"^3.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","typescript":"^5.7.2","@types/node":"20.19.43","@aevr/agents":"0.2.0","standard-version":"^9.5.0"},"peerDependencies":{"@aevr/agents":"^0.2.0"},"_npmOperationalInternal":{"tmp":"tmp/agents-openapi_0.1.1_1787413564687_0.7018212010652665","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@aevr/agents-openapi","version":"0.1.2","keywords":["agents","autonomous-agents","openapi","typescript"],"license":"MIT","_id":"@aevr/agents-openapi@0.1.2","maintainers":[{"name":"miracleio","email":"miracleficient@gmail.com"}],"homepage":"https://github.com/miracleonyenma/proxmox-management/tree/main/packages/agents-openapi#readme","bugs":{"url":"https://github.com/miracleonyenma/proxmox-management/issues"},"bin":{"aevr-agents-openapi":"./dist/cli.js"},"dist":{"shasum":"13ef4641b98f8092bf9f1307d877f46be77f6bbe","tarball":"https://registry.npmjs.org/@aevr/agents-openapi/-/agents-openapi-0.1.2.tgz","fileCount":47,"integrity":"sha512-u9pPaoKxU/H2QO/AVo/t0IDpZG2m8oeyBHGY7Uxp2VwUtIsrxScFHZAgpUpLugioYPIL7tExupeeuAu5bF7qAw==","signatures":[{"sig":"MEYCIQDNra1vfm1ECsugQ1aaNFFScr0pWV8izDgS/iPXJCBJ1QIhAP3dVPXUazqNHtoTplhGIYn5+Sq6WxQbbSfrT8RJskjb","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":291336},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"tsx --test src/*.test.ts src/**/*.test.ts","build":"tsc -p . && node scripts/make-cli-executable.mjs","release":"standard-version --tag-prefix agents-openapi@v","typecheck":"tsc --noEmit","release:major":"standard-version --release-as major --tag-prefix agents-openapi@v","release:minor":"standard-version --release-as minor --tag-prefix agents-openapi@v","release:patch":"standard-version --release-as patch --tag-prefix agents-openapi@v","verify:exports":"node scripts/check-exports.mjs","verify:package":"node scripts/verify-package.mjs"},"_npmUser":{"name":"miracleio","email":"miracleficient@gmail.com"},"repository":{"url":"git+https://github.com/miracleonyenma/proxmox-management.git","type":"git","directory":"packages/agents-openapi"},"description":"OpenAPI 3.1 capability generation and authenticated HTTP execution for @aevr/agents.","directories":{},"sideEffects":false,"_nodeVersion":"24.14.0","dependencies":{"ajv":"^8.20.0","yaml":"^2.9.0","ajv-formats":"^3.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","typescript":"^5.7.2","@types/node":"20.19.43","@aevr/agents":"0.5.1","standard-version":"^9.5.0"},"peerDependencies":{"@aevr/agents":"^0.5.0"},"_npmOperationalInternal":{"tmp":"tmp/agents-openapi_0.1.2_1788357647705_0.410976673740423","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"_id":"@aevr/agents-openapi@0.1.3","bin":{"aevr-agents-openapi":"dist/cli.js"},"bugs":{"url":"https://github.com/miracleonyenma/proxmox-management/issues"},"dist":{"shasum":"8b7b7d67baabdcdbe0c868ddde397a59e3b079c1","tarball":"https://registry.npmjs.org/@aevr/agents-openapi/-/agents-openapi-0.1.3.tgz","fileCount":47,"integrity":"sha512-oSpHc8GtTLex4QODD+68wMpE6CcToLM6wM3nlKpeYYzO6NzzSdHGgpweYtdmNrpJJDLt205wnnoW9aUGNMMxkg==","signatures":[{"sig":"MEYCIQCpkibJnW8NCkVckbQ7txTFhyaFHYTBKFuOmySRxn8aXAIhALAvnJja4AyQZBFG76SGkQvtssLip1g1qCRKccyWfT7C","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD8lHoFFBjRLpckACX4N/YYZ884IdwFRXmKfU7gNEAr+AIhAI6HMKmiVo7AeXdipYjdz0YvYyOUahVc5JNKF2DvV/vC"}],"unpackedSize":292469},"main":"./dist/index.js","name":"@aevr/agents-openapi","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"5c0127cf2968bf34bfc7fafc6a9327f09930e005","license":"MIT","scripts":{"test":"tsx --test src/*.test.ts src/**/*.test.ts","build":"tsc -p . && node scripts/make-cli-executable.mjs","release":"standard-version --tag-prefix agents-openapi@v","typecheck":"tsc --noEmit","release:major":"standard-version --release-as major --tag-prefix agents-openapi@v","release:minor":"standard-version --release-as minor --tag-prefix agents-openapi@v","release:patch":"standard-version --release-as patch --tag-prefix agents-openapi@v","prepublishOnly":"npm test && npm run typecheck && npm run build && npm run verify:exports && npm run verify:package","verify:exports":"node scripts/check-exports.mjs","verify:package":"node scripts/verify-package.mjs"},"version":"0.1.3","_npmUser":{"name":"miracleio","email":"miracleficient@gmail.com"},"homepage":"https://github.com/miracleonyenma/proxmox-management/tree/main/packages/agents-openapi#readme","keywords":["agents","autonomous-agents","openapi","typescript"],"repository":{"url":"git+https://github.com/miracleonyenma/proxmox-management.git","type":"git","directory":"packages/agents-openapi"},"_npmVersion":"11.9.0","description":"OpenAPI 3.1 capability generation and authenticated HTTP execution for @aevr/agents.","directories":{},"maintainers":[{"name":"miracleio","email":"miracleficient@gmail.com"}],"sideEffects":false,"_nodeVersion":"24.14.0","dependencies":{"ajv":"^8.20.0","yaml":"^2.9.0","ajv-formats":"^3.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@11.2.2+sha512.36e6621fad506178936455e70247b8808ef4ec25797a9f437a93281a020484e2607f6a469a22e982987c3dbb8866e3071514ab10a4a1749e06edcd1ec118436f","devDependencies":{"tsx":"^4.20.6","typescript":"^5.7.2","@types/node":"20.19.43","@aevr/agents":"workspace:*","standard-version":"^9.5.0"},"peerDependencies":{"@aevr/agents":"^0.5.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agents-openapi_0.1.3_1788779038688_0.40437372373209923"}}},"time":{"created":"2026-08-22T15:42:37.314Z","modified":"2026-09-07T11:03:58.969Z","0.1.0":"2026-08-22T15:42:37.609Z","0.1.1":"2026-08-22T15:46:04.852Z","0.1.2":"2026-09-02T14:00:47.857Z","0.1.3":"2026-09-07T11:03:58.780Z"},"bugs":{"url":"https://github.com/miracleonyenma/proxmox-management/issues"},"license":"MIT","homepage":"https://github.com/miracleonyenma/proxmox-management/tree/main/packages/agents-openapi#readme","keywords":["agents","autonomous-agents","openapi","typescript"],"repository":{"url":"git+https://github.com/miracleonyenma/proxmox-management.git","type":"git","directory":"packages/agents-openapi"},"description":"OpenAPI 3.1 capability generation and authenticated HTTP execution for @aevr/agents.","maintainers":[{"name":"miracleio","email":"miracleficient@gmail.com"}],"readme":"# @aevr/agents-openapi\n\nOpenAPI 3.1 operation discovery and document loading for autonomous application agents.\n\n## Status\n\nThe package parses JSON or YAML OpenAPI 3.1 documents, discovers operations with stable `operationId` values, filters them by ID, tag, extension, or policy, resolves local and externally loaded references, caches URL-loaded documents with ETag revalidation, strictly normalizes operation request and response schemas, generates core-valid capability catalogs, and executes generated operations through an authenticated HTTP adapter.\n\nThe initial package release covers parsing through durable-host composition boundaries. Applications remain responsible for current membership/permission adapters, credential issuance, result sanitization, policy engines, approval APIs, and audit delivery.\n\nApproval suspension, durable action records, and host audit integration remain separate package milestones.\n\n## Parsing and selection\n\n```ts\nimport { parseOpenApiDocument } from \"@aevr/agents-openapi\";\n\nconst parsed = parseOpenApiDocument(source, {\n  includeTags: [\"projects\"],\n  extensions: { \"x-aevr-agent-enabled\": true },\n  policy: (operation) => operation.extensions[\"x-aevr-risk\"] !== \"forbidden\",\n});\n\nfor (const operation of parsed.operations) {\n  console.log(operation.operationId, operation.method, operation.path);\n}\n```\n\nOperations without stable, unique IDs are excluded and reported through `diagnostics`.\n\n## Schema normalization\n\n```ts\nimport { normalizeOpenApiOperations } from \"@aevr/agents-openapi\";\n\nconst normalized = await normalizeOpenApiOperations(parsed, {\n  baseUrl: \"https://app.example/openapi.yaml\",\n  loadReference: async (url) => (await fetch(url)).text(),\n});\n```\n\nEach included operation has closed path, query, and header object schemas, an optional JSON request body, and deterministic exact, range, and default responses. Response ranges explicitly exclude exact statuses that take precedence. Local and nested external references, boolean schemas, nullable fields, enums, `allOf`, constrained `anyOf`, and provably exclusive `oneOf` branches are normalized recursively.\n\nNormalization excludes an entire operation with a typed diagnostic when model-authored request input or a response contract is ambiguous or unsafe. It never substitutes unconstrained request input. Explicitly freeform response fragments remain intact for truthful response modeling and downstream result sanitization.\n\n## Capability catalogs\n\n```ts\nimport {\n  createOpenApiCapabilityCatalogSnapshot,\n  generateOpenApiCapabilities,\n} from \"@aevr/agents-openapi\";\n\nconst catalog = generateOpenApiCapabilities(normalized, {\n  resolveResultPolicy(policyId, secretFields) {\n    if (policyId === \"standard\") {\n      return { maxBytes: 32_768, maxItems: 100, secretFields };\n    }\n    return undefined;\n  },\n});\n\nconst snapshot = createOpenApiCapabilityCatalogSnapshot(catalog);\n```\n\nGenerated descriptors are validated against `@aevr/agents`, and the immutable catalog carries a canonical SHA-256 hash. Inputs use closed `path`, `query`, `headers`, and `body` partitions. Executor descriptors preserve method, path template, JSON media type, parameter serialization, response precedence, resource/project bindings, approval policy, and result-policy identity for an HTTP adapter.\n\nCapability IDs come from reviewed `x-aevr-capability-id` metadata. Model tool names are deterministic lowercase identifiers capped at 64 characters with collision-resistant hash suffixes. Delete permission metadata maps to the core write permission while the executor retains the HTTP method. Public operations omit `requiredPermission`; resource kind and parameter metadata remain intact.\n\nHigh and critical operations without approval metadata, unknown result policies, invalid capability versions, duplicate IDs/names, disabled operations, and normalization failures remain explicit diagnostics rather than partially generated tools. When OpenAPI `info.version` is not semantic version text, pass a semantic `version` option.\n\n## HTTP execution\n\n```ts\nimport { createOpenApiCapabilityExecutor } from \"@aevr/agents-openapi\";\n\nconst executor = createOpenApiCapabilityExecutor(capability, {\n  baseUrl: \"https://app.example/api\",\n  acquireAccessToken: async (context, _capability, signal) =>\n    credentialService.exchange(context.runContext.credentialHandle, { signal }),\n  sanitizeResult(value, policy) {\n    return hostResultPolicy.prepare(value, policy).output.value;\n  },\n});\n```\n\nThe access token and credential handle are trusted runtime values and never appear in model-authored input. Execution validates tool input and raw HTTP output with JSON Schema, checks principal/run identity parity, serializes OpenAPI path/query/header/body bindings, injects immutable correlation and supported-idempotency headers, and validates the sanitized public output contract.\n\nThe adapter permits one configured HTTP(S) base URL, rejects traversal and protected headers, disables redirects, and bounds the entire request, streamed response, and sanitized result. Token acquisition, fetch, response reads, and sanitization are all deadline/cancellation aware even when injected providers ignore abort signals. Non-2xx responses become redacted `NormalizedError` values. Network loss after unsupported side effects becomes `HTTP_OUTCOME_UNKNOWN`; failures after a response is known never do.\n\nThe host owns credential exchange and result-policy implementation. `acquireAccessToken` should mint a short-lived member-agent token from the opaque credential handle. `sanitizeResult` should call the host's canonical redaction/bounding utility; raw response values are validated before that callback and are never returned directly.\n\n## Constrained fallback\n\n```ts\nimport { createConstrainedApiRequestTool } from \"@aevr/agents-openapi\";\n\nconst fallback = createConstrainedApiRequestTool(catalog, {\n  baseUrl: \"https://app.example/api\",\n  acquireAccessToken,\n  sanitizeResult,\n});\n```\n\n`host.api.request` accepts only `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`, an origin-relative path without query/fragment syntax, scalar query values, an optional JSON body, and an optional idempotency key that must equal trusted execution context. It accepts no headers, hostname, port, credential, subject, project, task, run, redirect, or timeout input.\n\nThe resolver matches only operations in the immutable generated catalog, applies segment-level static precedence, rejects ambiguous route shapes, and exposes the exact capability metadata for later policy enforcement. It is bound to the run's capability-catalog hash before authentication. Unknown, excluded, method-mismatched, stale-catalog, and required-header operations are denied before token acquisition or fetch.\n\nAbsolute and protocol-relative URLs, invalid encoding, traversal, encoded/double-encoded traversal, backslashes, template syntax, control characters, query strings, and fragments are rejected. Known requests delegate to the explicit HTTP executor, retaining its token isolation, correlation, idempotency, schema validation, redaction, limits, manual redirect rejection, cancellation, and unknown-outcome handling.\n\n## Active catalogs and search\n\n```ts\nimport { createActiveOpenApiCapabilityCatalog } from \"@aevr/agents-openapi\";\n\nconst active = await createActiveOpenApiCapabilityCatalog(catalog, {\n  principal,\n  runContext: runContextWithoutCatalogHash,\n  agentGrant,\n  taskGrant,\n  phaseCapabilityIds,\n  maxRisk: \"high\",\n  providerToolLimit: 32,\n  preferredCapabilityIds: [\"agenticTrading.instances.byId.get\"],\n}, eligibilityAdapter);\n\nconst immutableRunContext = {\n  ...runContextWithoutCatalogHash,\n  capabilityCatalogHash: active.catalog.hash,\n};\n```\n\nThe package intersects canonical agent and task grants, then filters by current principal status, project membership, phase, risk cap, resource authority, host authorization, and host policy. Policy `deny` excludes a capability; `require_approval` remains eligible for later approval enforcement. Adapter outages produce typed fail-closed exclusions without exposing backend details.\n\nProvider limits select a deterministic active subset. Preferred eligible IDs rank first, followed by lower risk and stable capability ID. `active.catalog` is directly compatible with explicit executors and the constrained fallback. Equivalent authority produces the same active hash independent of source order.\n\n`active.search(query, limit)` searches every eligible capability, including provider-deferred entries, but never returns denied tools. Search is a bounded runtime API rather than an automatically advertised model tool, so it does not consume an extra provider slot. A host can rebuild with selected search results in `preferredCapabilityIds`; deferred capabilities remain non-executable until that new snapshot is bound.\n\nExecution uses `active.getForExecution({ capabilityId, toolInput, runContext })`. It requires the derived active hash and identical run IDs, rechecks live membership, authorization, and policy, and applies exact project/resource IDs from validated path/query input with canonical task-grant checks. Permission revocation therefore blocks the next lookup even if a capability appeared in the original advertisement.\n\n## References\n\n```ts\nimport { OpenApiReferenceResolver } from \"@aevr/agents-openapi\";\n\nconst resolver = new OpenApiReferenceResolver(parsed.document, {\n  baseUrl: \"https://app.example/openapi.yaml\",\n  load: async (url) => (await fetch(url)).text(),\n});\n\nconst schema = await resolver.resolve(\"./schemas.yaml#/schemas/Project\");\n```\n\nApplications own external loading and its network policy. The resolver performs no network access unless a loader is supplied.\n\n## URL cache\n\n`OpenApiDocumentCache` loads through global `fetch` or an injected implementation. Cached ETags are sent with `If-None-Match`; `304` responses reuse the parsed document, while successful changed responses replace it. `versionToken` uses the ETag when available and otherwise combines the OpenAPI and application document versions.\n\n## Development\n\n```bash\npnpm test\npnpm run typecheck\npnpm run build\npnpm run verify:exports\npnpm run verify:package\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}