{"_id":"@aigrc/runtime","name":"@aigrc/runtime","dist-tags":{"latest":"3.1.1"},"versions":{"3.1.1":{"name":"@aigrc/runtime","version":"3.1.1","description":"AIGOS Runtime Governance System - Identity Manager, Policy Engine, and Runtime Controls","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./identity":{"import":"./dist/identity/index.js","types":"./dist/identity/index.d.ts"},"./policy":{"import":"./dist/policy/index.js","types":"./dist/policy/index.d.ts"},"./telemetry":{"import":"./dist/telemetry/index.js","types":"./dist/telemetry/index.d.ts"},"./kill-switch":{"import":"./dist/kill-switch/index.js","types":"./dist/kill-switch/index.d.ts"},"./capability":{"import":"./dist/capability/index.js","types":"./dist/capability/index.d.ts"},"./a2a":{"import":"./dist/a2a/index.js","types":"./dist/a2a/index.d.ts"},"./license":{"import":"./dist/license/index.js","types":"./dist/license/index.d.ts"}},"dependencies":{"@aigrc/core":"3.1.0"},"devDependencies":{"@types/node":"^20.10.0","tsup":"^8.0.0","typescript":"^5.3.0","vitest":"^1.0.0","rimraf":"^5.0.0"},"peerDependencies":{"@opentelemetry/api":"^1.7.0","@opentelemetry/sdk-node":"^0.46.0"},"peerDependenciesMeta":{"@opentelemetry/api":{"optional":true},"@opentelemetry/sdk-node":{"optional":true}},"keywords":["aigos","ai-governance","runtime","identity","policy-engine","kill-switch","telemetry","a2a","jwt","mutual-authentication","license","feature-gating"],"author":{"name":"Pango Labs"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/aigrc/aigrc.git","directory":"packages/runtime"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"engines":{"node":">=18.0.0"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"eslint src/","typecheck":"tsc --noEmit","clean":"rimraf dist"},"_id":"@aigrc/runtime@3.1.1","bugs":{"url":"https://github.com/aigrc/aigrc/issues"},"homepage":"https://github.com/aigrc/aigrc#readme","_integrity":"sha512-qYWieDQT1R30tFJzMDpthWmRXPqJQyHzNuXU/U1WeZ73a3ODHra0BSyC+DJq7aC3nUIcf61EiKFMKiX1kggx8A==","_resolved":"/tmp/51189c4df1d46bcff7969dd2205eda9b/aigrc-runtime-3.1.1.tgz","_from":"file:aigrc-runtime-3.1.1.tgz","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-qYWieDQT1R30tFJzMDpthWmRXPqJQyHzNuXU/U1WeZ73a3ODHra0BSyC+DJq7aC3nUIcf61EiKFMKiX1kggx8A==","shasum":"8bbc41d80211240e0aea05a3aa8ac44f9bbac1fb","tarball":"https://registry.npmjs.org/@aigrc/runtime/-/runtime-3.1.1.tgz","fileCount":27,"unpackedSize":1270733,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH8tBX6G8sTrd9y/kgA7EFadbjLPuuKTm28H7rme7iL1AiBmE9zag97qYhs3GfaXpK73SlebAqGP9ClUMzSqQsLM/w=="}]},"_npmUser":{"name":"ai-grc","email":"admin@aigrc.dev"},"directories":{},"maintainers":[{"name":"ai-grc","email":"admin@aigrc.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/runtime_3.1.1_1772297938548_0.5534466608665272"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-28T16:58:58.488Z","3.1.1":"2026-02-28T16:58:58.785Z","modified":"2026-02-28T16:58:58.973Z"},"maintainers":[{"name":"ai-grc","email":"admin@aigrc.dev"}],"description":"AIGOS Runtime Governance System - Identity Manager, Policy Engine, and Runtime Controls","homepage":"https://github.com/aigrc/aigrc#readme","keywords":["aigos","ai-governance","runtime","identity","policy-engine","kill-switch","telemetry","a2a","jwt","mutual-authentication","license","feature-gating"],"repository":{"type":"git","url":"git+https://github.com/aigrc/aigrc.git","directory":"packages/runtime"},"author":{"name":"Pango Labs"},"bugs":{"url":"https://github.com/aigrc/aigrc/issues"},"license":"Apache-2.0","readme":"# @aigrc/runtime\n\nRuntime Governance System for AI Agents - Identity Manager, Policy Engine (\"The Bouncer\"), and Runtime Controls.\n\n## Features\n\n- **Identity Manager** (SPEC-RT-002): Cryptographic identity establishment with Golden Thread verification\n- **Policy Engine** (SPEC-RT-003): Real-time permission evaluation with <2ms P99 latency target\n- **Guard Decorator**: TypeScript decorator for protecting functions with governance checks\n- **Capability Decay**: Child agents inherit restricted capabilities from parents\n- **Mode Management**: NORMAL, SANDBOX, and RESTRICTED operating modes\n\n## Installation\n\n```bash\npnpm add @aigrc/runtime\n```\n\n## Quick Start\n\n```typescript\nimport {\n  createIdentityManager,\n  createPolicyEngine,\n  configureGuard,\n  guard,\n} from '@aigrc/runtime';\n\n// Create managers\nconst identityManager = createIdentityManager({\n  maxSpawnDepth: 5,\n  verificationFailureMode: 'SANDBOX', // or 'FAIL'\n});\n\nconst policyEngine = createPolicyEngine({\n  dryRun: false, // Set true to log without enforcing\n});\n\n// Create identity for your agent\nconst identity = await identityManager.createIdentity({\n  assetCardPath: '.aigrc/cards/my-agent.yaml',\n});\n\n// Configure guards\nconfigureGuard({\n  identityProvider: () => identity,\n  policyChecker: async (id, ctx) => {\n    const decision = policyEngine.checkPermissionSync(id, ctx.action, ctx.resource);\n    return { allowed: decision.allowed, reason: decision.reason };\n  },\n});\n\n// Use guards on agent methods\nclass MyAgent {\n  @guard('call_api')\n  async callExternalAPI(url: string) {\n    return fetch(url);\n  }\n\n  @guard('read_file', { resource: (args) => args[0] })\n  async readFile(path: string) {\n    // Resource is extracted from first argument\n    return fs.readFile(path);\n  }\n}\n```\n\n## Identity Manager\n\nThe Identity Manager establishes cryptographic identity for AI agents at runtime:\n\n```typescript\nconst identityManager = createIdentityManager({\n  maxSpawnDepth: 5,\n  verificationFailureMode: 'SANDBOX', // or 'FAIL'\n  telemetryEnabled: true,\n});\n\n// Create root identity\nconst identity = await identityManager.createIdentity({\n  assetCardPath: '.aigrc/cards/my-agent.yaml',\n});\n\nconsole.log(identity.instance_id);  // UUID\nconsole.log(identity.verified);     // true if Golden Thread verified\nconsole.log(identity.mode);         // 'NORMAL', 'SANDBOX', or 'RESTRICTED'\n\n// Spawn child agent (with capability decay)\nconst childIdentity = await identityManager.spawnChild(identity, {\n  assetCardPath: '.aigrc/cards/child-agent.yaml',\n});\n\n// Request mode transition\nconst result = await identityManager.requestModeTransition(identity, {\n  targetMode: 'RESTRICTED',\n  reason: 'Entering maintenance mode',\n});\n```\n\n## Policy Engine\n\nThe Policy Engine evaluates permissions with short-circuit evaluation:\n\n```typescript\nconst policyEngine = createPolicyEngine({\n  dryRun: false,\n  defaultAllow: false,\n});\n\n// Check permission\nconst decision = await policyEngine.checkPermission(\n  identity,\n  'call_api',        // action\n  'api.example.com', // resource (optional)\n  { cost: 0.01 }     // context (optional)\n);\n\nif (!decision.allowed) {\n  console.log(`Denied by: ${decision.denied_by}`);\n  console.log(`Reason: ${decision.reason}`);\n}\n\n// Record cost for budget tracking\npolicyEngine.recordCost(identity.instance_id, 0.05);\n\n// Register custom check\npolicyEngine.registerCustomCheck('pii-check', (identity, action, resource) => {\n  if (resource?.includes('pii')) {\n    return {\n      allowed: false,\n      code: 'PII_ACCESS',\n      reason: 'PII access requires explicit approval',\n    };\n  }\n  return null; // Passed\n});\n\n// Kill switch integration\npolicyEngine.updateKillSwitch('TERMINATE', { instanceId: 'some-agent-id' });\npolicyEngine.updateKillSwitch('PAUSE', { assetId: 'dangerous-agent' });\n```\n\n## Guard Decorator\n\nProtect functions with policy checks:\n\n```typescript\nimport { guard, guardAsync, checkGuard } from '@aigrc/runtime';\n\n// Using decorator\nclass MyAgent {\n  @guard('expensive_operation', {\n    metadata: { cost_tier: 'high' },\n  })\n  async runExpensiveOperation() {\n    // Only executes if allowed\n  }\n}\n\n// Functional style\nconst protectedFetch = guardAsync('fetch', async (url: string) => {\n  return fetch(url);\n}, { resource: (args) => args[0] });\n\n// Manual check\nconst result = await checkGuard('dangerous_action', {\n  resource: 'sensitive-data',\n});\nif (!result.allowed) {\n  console.error(`Action denied: ${result.reason}`);\n}\n```\n\n## Evaluation Chain\n\nThe Policy Engine evaluates in this order (short-circuit on denial):\n\n1. **Kill Switch** [O(1)] - Check if agent is terminated/paused\n2. **Mode Check** [O(1)] - RESTRICTED mode limits actions\n3. **Capability** [O(n)] - Check allowed/denied tools\n4. **Resource Deny** [O(n)] - Check denied domains\n5. **Resource Allow** [O(n)] - Check allowed domains\n6. **Budget** [O(1)] - Check cost limits\n7. **Custom Checks** [O(k)] - User-defined checks\n\n## Events\n\nSubscribe to events for telemetry and monitoring:\n\n```typescript\nidentityManager.onEvent((event) => {\n  switch (event.type) {\n    case 'identity.created':\n      console.log(`Agent ${event.identity.instance_id} started`);\n      break;\n    case 'identity.mode_changed':\n      console.log(`Mode: ${event.from} -> ${event.to}`);\n      break;\n  }\n});\n\npolicyEngine.onEvent((event) => {\n  if (event.type === 'policy.denied') {\n    console.log(`Denied: ${event.action} - ${event.decision.reason}`);\n  }\n});\n```\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md","_rev":"1-a2eacb3f8ed47898caebb066cd6d86b9"}