{"_id":"@aigrc/sdk","name":"@aigrc/sdk","dist-tags":{"latest":"3.1.1"},"versions":{"3.1.1":{"name":"@aigrc/sdk","version":"3.1.1","description":"Unified SDK for AIGOS - AI Governance Operating System. Provides createGovernedAgent(), @guard decorator, and Control Plane integration.","license":"Apache-2.0","author":{"name":"Pango Labs"},"homepage":"https://github.com/aigrc/aigrc#readme","repository":{"type":"git","url":"git+https://github.com/aigrc/aigrc.git","directory":"packages/sdk"},"bugs":{"url":"https://github.com/aigrc/aigrc/issues"},"keywords":["aigos","aigrc","ai-governance","runtime","sdk","guard","kill-switch","telemetry","control-plane","agent-governance"],"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"type":"module","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./client":{"types":"./dist/client/index.d.ts","import":"./dist/client/index.mjs","require":"./dist/client/index.js"},"./decorators":{"types":"./dist/decorators/index.d.ts","import":"./dist/decorators/index.mjs","require":"./dist/decorators/index.js"},"./telemetry":{"types":"./dist/telemetry/index.d.ts","import":"./dist/telemetry/index.mjs","require":"./dist/telemetry/index.js"}},"dependencies":{"@aigrc/core":"^3.1.0","eventemitter3":"^5.0.1","uuid":"^9.0.0"},"devDependencies":{"@types/node":"^20.10.0","@types/uuid":"^9.0.0","rimraf":"^5.0.0","tsup":"^8.0.1","typescript":"^5.3.0","vitest":"^1.0.0"},"peerDependencies":{"@opentelemetry/api":"^1.7.0"},"peerDependenciesMeta":{"@opentelemetry/api":{"optional":true}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest","test:coverage":"vitest --coverage","clean":"rimraf dist"},"_id":"@aigrc/sdk@3.1.1","_integrity":"sha512-nUGGxisfUYTafL50ONMYadLYdM/en9QTRK3XZeJNEgFXfu77CuHz7fV2Uk6xBbtaqsoWo/r9TI9f5sfY7HKOeg==","_resolved":"/tmp/19cd7baa1f600d89590fd0a893845a90/aigrc-sdk-3.1.1.tgz","_from":"file:aigrc-sdk-3.1.1.tgz","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-nUGGxisfUYTafL50ONMYadLYdM/en9QTRK3XZeJNEgFXfu77CuHz7fV2Uk6xBbtaqsoWo/r9TI9f5sfY7HKOeg==","shasum":"e10700f2f255907793bed63a0e1af60b428579f4","tarball":"https://registry.npmjs.org/@aigrc/sdk/-/sdk-3.1.1.tgz","fileCount":29,"unpackedSize":362220,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICy9SBdZ0MUp7QakbKepOFShdnQDL02R5uEiQQu5wd4cAiEA5JTFmyyk1qS5KSf1aK24dYLOS/F5vQQr+fjZb+hBsp0="}]},"_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/sdk_3.1.1_1772297938647_0.008169582023347832"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-28T16:58:58.585Z","3.1.1":"2026-02-28T16:58:58.827Z","modified":"2026-02-28T16:58:59.006Z"},"maintainers":[{"name":"ai-grc","email":"admin@aigrc.dev"}],"description":"Unified SDK for AIGOS - AI Governance Operating System. Provides createGovernedAgent(), @guard decorator, and Control Plane integration.","homepage":"https://github.com/aigrc/aigrc#readme","keywords":["aigos","aigrc","ai-governance","runtime","sdk","guard","kill-switch","telemetry","control-plane","agent-governance"],"repository":{"type":"git","url":"git+https://github.com/aigrc/aigrc.git","directory":"packages/sdk"},"author":{"name":"Pango Labs"},"bugs":{"url":"https://github.com/aigrc/aigrc/issues"},"license":"Apache-2.0","readme":"# @aigrc/sdk\n\n> The unified SDK for building governed AI agents with the AI Governance Operating System (AIGOS)\n\n[![npm version](https://img.shields.io/npm/v/@aigrc/sdk.svg)](https://www.npmjs.com/package/@aigrc/sdk)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\n## Overview\n\n`@aigrc/sdk` provides everything you need to build AI agents with built-in governance, policy enforcement, and compliance. It integrates seamlessly with the AIGOS Control Plane for centralized management, HITL (Human-in-the-Loop) approvals, and kill switch capabilities.\n\n### Key Features\n\n- 🛡️ **Policy Enforcement** - Declarative permission checking with capability manifests\n- 🔗 **Golden Thread Protocol** - Cryptographic linking to business authorization\n- 👤 **HITL Integration** - Request human approval for sensitive operations\n- ⚡ **Kill Switch** - Remote termination and control capabilities\n- 🌳 **Hierarchical Agents** - Spawn child agents with capability decay\n- 📊 **Telemetry** - Built-in observability and audit logging\n- 🎯 **Decorator Support** - Method-level governance with `@guard`\n\n## Installation\n\n```bash\nnpm install @aigrc/sdk\n# or\npnpm add @aigrc/sdk\n# or\nyarn add @aigrc/sdk\n```\n\n## Quick Start\n\n### Basic Agent\n\n```typescript\nimport { createGovernedAgent } from '@aigrc/sdk';\n\n// Create a governed agent\nconst agent = await createGovernedAgent({\n  name: 'order-processor',\n  version: '1.0.0',\n\n  // Define what this agent can do\n  capabilities: {\n    allowed_tools: ['database:read', 'api:orders:*'],\n    denied_tools: ['admin:*'],\n    max_cost_per_session: 10.00,\n  },\n});\n\n// Check permission before action\nconst result = await agent.checkPermission('database:read', 'orders');\nif (result.allowed) {\n  // Perform the action\n}\n\n// Graceful shutdown\nawait agent.shutdown();\n```\n\n### Using the @guard Decorator\n\n```typescript\nimport { createGovernedAgent, guard, setAgent } from '@aigrc/sdk';\n\nclass UserService {\n  @guard({ action: 'database:read', resource: 'users' })\n  async getUsers() {\n    return await db.query('SELECT * FROM users');\n  }\n\n  @guard({ action: 'admin:delete', requireApproval: true })\n  async deleteAllUsers() {\n    // Requires HITL approval before executing\n  }\n}\n\nconst agent = await createGovernedAgent({ ... });\nconst service = new UserService();\nsetAgent(service, agent);\n\n// This will check permission automatically\nconst users = await service.getUsers();\n```\n\n### Control Plane Integration\n\n```typescript\nconst agent = await createGovernedAgent({\n  name: 'production-worker',\n  version: '1.0.0',\n\n  // Connect to Control Plane\n  controlPlane: 'https://cp.aigos.io',\n  apiKey: process.env.AIGOS_API_KEY,\n\n  // Enable kill switch\n  killSwitch: {\n    enabled: true,\n    onCommand: async (cmd) => {\n      console.log(`Received: ${cmd.command}`);\n    },\n  },\n\n  // Enable telemetry\n  telemetry: true,\n\n  // Link to business authorization\n  goldenThread: {\n    ticket_id: 'JIRA-456',\n    approved_by: 'security@company.com',\n    approved_at: '2024-01-01T00:00:00Z',\n  },\n});\n```\n\n## API Reference\n\n### `createGovernedAgent(config)`\n\nCreates a new governed agent instance.\n\n#### Config Options\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `name` | `string` | Yes | Agent name |\n| `version` | `string` | No | Semantic version (default: \"1.0.0\") |\n| `controlPlane` | `string` | No | Control Plane URL |\n| `apiKey` | `string` | No | API key for Control Plane |\n| `capabilities` | `CapabilitiesManifest` | No | Capability restrictions |\n| `goldenThread` | `GoldenThread` | No | Business authorization |\n| `killSwitch` | `KillSwitchConfig` | No | Kill switch settings |\n| `telemetry` | `boolean \\| TelemetryConfig` | No | Telemetry settings |\n| `mode` | `OperatingMode` | No | Operating mode |\n| `parent` | `ParentConfig` | No | Parent agent for spawning |\n\n#### CapabilitiesManifest\n\n```typescript\ninterface CapabilitiesManifest {\n  allowed_tools: string[];      // Actions agent can perform\n  denied_tools: string[];       // Explicitly denied actions\n  allowed_domains: string[];    // Allowed network domains\n  denied_domains: string[];     // Blocked network domains\n  may_spawn_children: boolean;  // Can spawn child agents\n  max_child_depth: number;      // Maximum spawn depth\n  capability_mode: 'decay' | 'inherit' | 'explicit';\n  max_cost_per_session?: number;\n  max_cost_per_day?: number;\n  max_tokens_per_call?: number;\n}\n```\n\n### `guard(options)`\n\nDecorator for method-level governance.\n\n```typescript\n@guard({\n  action: 'database:read',      // Required: action to check\n  resource: 'users/${userId}',  // Optional: resource (supports interpolation)\n  requireApproval: false,       // Optional: require HITL approval\n  fallback: 'deny',             // Optional: behavior when offline\n})\n```\n\n### `setAgent(instance, agent)`\n\nAttaches a governed agent to a class instance.\n\n```typescript\nconst service = new MyService();\nsetAgent(service, agent);\n```\n\n### `getAgent(instance)`\n\nRetrieves the governed agent from a class instance.\n\n```typescript\nconst agent = getAgent(service);\n```\n\n### `withGuard(fn, agent, options)`\n\nFunctional wrapper for governance (non-decorator alternative).\n\n```typescript\nconst guardedFn = withGuard(\n  myFunction,\n  agent,\n  { action: 'database:read' }\n);\n```\n\n## Capability Decay\n\nWhen spawning child agents, capabilities decay based on the `capability_mode`:\n\n### Decay Mode (Default)\n- Numeric limits reduced by 20% per generation\n- Tools inherited from parent\n- Spawn depth limited by `max_child_depth`\n\n### Inherit Mode\n- Full capability inheritance\n- Same limits as parent\n\n### Explicit Mode\n- Child must specify all capabilities\n- No automatic inheritance\n\n```typescript\n// Parent with $100 cost limit\nconst parent = await createGovernedAgent({\n  capabilities: {\n    may_spawn_children: true,\n    max_child_depth: 3,\n    capability_mode: 'decay',\n    max_cost_per_session: 100,\n  },\n});\n\n// Child gets $80 limit (100 * 0.8)\nconst child = await parent.spawn({ name: 'child' });\n\n// Grandchild gets $64 limit (80 * 0.8)\nconst grandchild = await child.spawn({ name: 'grandchild' });\n```\n\n## Golden Thread Protocol\n\nThe Golden Thread creates an unbroken link from runtime actions to business authorization:\n\n```\n┌─────────────────────┐\n│   Business Request  │  ← Jira/ServiceNow ticket\n└──────────┬──────────┘\n           │\n┌──────────▼──────────┐\n│  Security Approval  │  ← approved_by, approved_at\n└──────────┬──────────┘\n           │\n┌──────────▼──────────┐\n│   Agent Instance    │  ← instance_id, golden_thread_hash\n└──────────┬──────────┘\n           │\n┌──────────▼──────────┐\n│   Runtime Actions   │  ← Audit log with full traceability\n└─────────────────────┘\n```\n\n```typescript\nconst agent = await createGovernedAgent({\n  goldenThread: {\n    ticket_id: 'JIRA-123',\n    approved_by: 'security@company.com',\n    approved_at: '2024-01-01T00:00:00Z',\n    signature: 'sha256:...',  // Optional cryptographic signature\n  },\n});\n```\n\n## HITL (Human-in-the-Loop)\n\nRequest human approval for sensitive operations:\n\n```typescript\nconst approval = await agent.requestApproval({\n  action: 'database:delete',\n  resource: 'production/users',\n  reason: 'Quarterly cleanup of inactive accounts',\n  context: {\n    affected_records: 5000,\n    reversible: true,\n  },\n  timeout: 300000,  // 5 minutes\n  fallback: 'deny', // Deny if offline/timeout\n});\n\nif (approval.approved) {\n  // Proceed with operation\n} else {\n  // Handle denial\n}\n```\n\n## Kill Switch\n\nThe kill switch provides remote control capabilities:\n\n```typescript\nconst agent = await createGovernedAgent({\n  killSwitch: {\n    enabled: true,\n    onCommand: async (command) => {\n      switch (command.command) {\n        case 'pause':\n          // Agent paused, checkPermission returns false\n          break;\n        case 'resume':\n          // Agent resumed\n          break;\n        case 'terminate':\n          // Agent shutting down\n          break;\n        case 'restart':\n          // Trigger restart logic\n          break;\n      }\n    },\n  },\n});\n```\n\n## Operating Modes\n\n| Mode | Description |\n|------|-------------|\n| `NORMAL` | Standard operation with full capabilities |\n| `SANDBOX` | Isolated sandbox mode for testing/development |\n| `RESTRICTED` | Restricted mode with limited capabilities |\n\n## Examples\n\nSee the `examples/` directory for complete examples:\n\n- `basic-agent.ts` - Simple agent with permission checking\n- `guard-decorator.ts` - Using @guard for method-level governance\n- `child-spawning.ts` - Hierarchical agents with capability decay\n- `golden-thread.ts` - Golden Thread Protocol integration\n- `langchain-integration.ts` - LangChain agent governance\n- `control-plane-integration.ts` - Full Control Plane integration\n\nRun examples with:\n\n```bash\nnpx tsx examples/basic-agent.ts\n```\n\n## License\n\nApache-2.0 - See [LICENSE](LICENSE) for details.\n\n## Related Packages\n\n- `@aigrc/core` - Core schemas and types\n- `@aigrc/cli` - Command-line interface\n- `@aigrc/mcp` - Model Context Protocol server\n\n## Support\n\n- 📖 [Documentation](https://docs.aigos.dev)\n- 💬 [Discord Community](https://discord.gg/aigos)\n- 🐛 [Issue Tracker](https://github.com/aigrc/aigrc/issues)\n","readmeFilename":"README.md","_rev":"1-25118beddc38bea98e2acd818c67d315"}