{"_id":"@ai-employee-sdk/core","name":"@ai-employee-sdk/core","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@ai-employee-sdk/core","version":"0.2.0","description":"Autonomous agent primitives for the Vercel AI SDK — permissions, cost tracking, server-side interrupts","license":"Apache-2.0","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","clean":"rm -rf dist *.tsbuildinfo","test":"vitest run","test:watch":"vitest"},"repository":{"type":"git","url":"git+https://github.com/ai-employee-sdk/ai-employee.git","directory":"packages/core"},"homepage":"https://github.com/ai-employee-sdk/ai-employee#readme","bugs":{"url":"https://github.com/ai-employee-sdk/ai-employee/issues"},"keywords":["ai","agent","ai-sdk","vercel","autonomous","tools","permissions","membrane","cost-tracking","interrupts"],"peerDependencies":{"ai":">=7.0.0-beta.30 <8.0.0"},"peerDependenciesMeta":{"ai":{"optional":false}},"devDependencies":{"ai":"7.0.0-beta.30","@types/node":"^22.0.0","typescript":"^5.8.0","tsup":"^8.0.0","vitest":"^4.0.0"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"_id":"@ai-employee-sdk/core@0.2.0","gitHead":"3b834afca77990af3c5617ca456066055034512d","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-GCzFPtQuGQSJPRXHzCab76HjEvdmz3LnltXZM+DOpBGZnWA24ayuAPxDxB0wqQxjmVKlHmvZPr2BdE/lx3/Qpw==","shasum":"3158c159b9dfcba038f31ad76c791d9c6cba1ed0","tarball":"https://registry.npmjs.org/@ai-employee-sdk/core/-/core-0.2.0.tgz","fileCount":8,"unpackedSize":187928,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFqUJLmsTktR+2c/HeRK844yDO7qXlizyt0Gweo3dBlmAiBkV14jytOelMFfbMwMBl2WZ2PSLpiK3cbWoXYu6Tzr0w=="}]},"_npmUser":{"name":"progrmoiz","email":"progrmoiz@gmail.com"},"directories":{},"maintainers":[{"name":"progrmoiz","email":"progrmoiz@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_0.2.0_1774157636563_0.521822346648755"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-22T05:33:56.507Z","0.2.0":"2026-03-22T05:33:56.710Z","modified":"2026-03-22T05:33:56.869Z"},"maintainers":[{"name":"progrmoiz","email":"progrmoiz@gmail.com"}],"description":"Autonomous agent primitives for the Vercel AI SDK — permissions, cost tracking, server-side interrupts","homepage":"https://github.com/ai-employee-sdk/ai-employee#readme","keywords":["ai","agent","ai-sdk","vercel","autonomous","tools","permissions","membrane","cost-tracking","interrupts"],"repository":{"type":"git","url":"git+https://github.com/ai-employee-sdk/ai-employee.git","directory":"packages/core"},"bugs":{"url":"https://github.com/ai-employee-sdk/ai-employee/issues"},"license":"Apache-2.0","readme":"# @ai-employee-sdk/core\n\nComposable autonomy primitives for the [Vercel AI SDK](https://ai-sdk.dev). A toolbox, not a framework.\n\nAdd permissions, cost tracking, and server-side interrupts to any `generateText()` call — without replacing your existing agent code.\n\n> **Note:** This library requires AI SDK v7 (currently in beta). APIs may change as AI SDK v7 stabilizes.\n\n## Install\n\n```bash\nnpm install @ai-employee-sdk/core ai@latest\n```\n\n## Exports\n\n| Export | What it does |\n|--------|-------------|\n| `membrane({ tools, tiers })` | 4-tier tool permissions (AUTO / DRAFT / CONFIRM / BLOCK) |\n| `createCostTracker({ budget, pricing })` | Stateful USD cost tracking with per-model pricing |\n| `extractPendingApprovals(result)` | Detect CONFIRM tools awaiting human approval |\n| `createInterruptHandle(result, pending)` | Serialize agent state for KV storage |\n| `resolveInterrupt(handle, decisions)` | Rebuild messages from approve/deny/edit decisions |\n| `composePrepareStep(...fns)` | Merge N PrepareStepFunctions |\n| `budgetExceeded(config)` | Stop condition for token/USD budgets |\n| `tokenVelocityExceeded(config)` | Stop condition for token velocity |\n| `createHeartbeat(config)` | Concurrency guard + circuit breaker for polling agents |\n| `createMemoryPrepareStep(store, config)` | Inject memory snapshots into system prompt |\n| `EmployeeAgent` | Convenience wrapper composing membrane + memory + heartbeat |\n| `InMemoryStore` | Map-based MemoryStore for testing |\n| `explainTier(toolName, config)` | Debug API — shows why a tool got its tier |\n| `DEFAULT_MODEL_PRICING` | Pricing for 13 common models (GPT-4o, Claude, Gemini, etc.) |\n\n## Quick Start\n\n### Membrane — Tool Permissions\n\n```typescript\nimport { generateText } from 'ai';\nimport { openai } from '@ai-sdk/openai';\nimport { membrane } from '@ai-employee-sdk/core';\n\nconst m = membrane({\n  tools: { readFile, writeFile, deleteFile, sendEmail },\n  tiers: {\n    auto: ['readFile'],           // runs freely\n    draft: ['writeFile'],         // runs + logged\n    confirm: ['sendEmail'],       // needs human approval\n    block: ['deleteFile'],        // never runs\n  },\n});\n\nconst result = await generateText({\n  model: openai('gpt-4o-mini'),\n  tools: m.tools,\n  prepareStep: m.prepareStep,\n  maxSteps: 10,\n  prompt: 'Summarize the project and email the team.',\n});\n\nconsole.log(m.auditLog); // every tool call, all tiers\n```\n\n### Cost Tracking\n\n```typescript\nimport { createCostTracker, DEFAULT_MODEL_PRICING } from '@ai-employee-sdk/core';\n\nconst tracker = createCostTracker({\n  budget: 0.50, // USD\n  pricing: DEFAULT_MODEL_PRICING,\n});\n\nconst result = await generateText({\n  model: openai('gpt-4o-mini'),\n  tools: m.tools,\n  onStepFinish: tracker.onStepFinish,\n  stopWhen: tracker.stopCondition,\n  maxSteps: 20,\n  prompt: 'Research this topic thoroughly.',\n});\n\nconst snap = tracker.snapshot();\nconsole.log(`Cost: $${snap.totalCostUsd.toFixed(4)}, remaining: $${snap.remainingUsd.toFixed(4)}`);\n```\n\n### Server-Side Interrupts\n\nFor agents that run on cron jobs, webhooks, or serverless functions — where there's no UI to show approval dialogs.\n\n```typescript\nimport {\n  extractPendingApprovals,\n  createInterruptHandle,\n  resolveInterrupt,\n} from '@ai-employee-sdk/core';\n\n// 1. Agent runs, hits a CONFIRM tool -> needsApproval stops the loop\nconst result = await generateText({ model, tools: m.tools, maxSteps: 10, prompt });\n\n// 2. Check if any CONFIRM tools are waiting\nconst pending = extractPendingApprovals(result);\n\nif (pending.length > 0) {\n  // 3. Serialize state -> save to KV -> notify human (Slack, email, etc.)\n  const handle = createInterruptHandle(result, pending);\n  await kv.set(`interrupt:${handle.id}`, handle);\n  await notifyHuman(pending); // your notification logic\n  return; // function exits -- no compute cost while waiting\n}\n\n// ... hours later, human responds ...\n\n// 4. Load handle, resolve decisions, resume agent\nconst handle = await kv.get(`interrupt:${handleId}`);\nawait kv.delete(`interrupt:${handleId}`); // idempotency: delete before execute\n\nconst { messages, previousUsage } = resolveInterrupt(handle, [\n  { toolCallId: 'tc_3', action: 'approve', editedArgs: { days: 30 } },\n]);\n\n// 5. Resume with the approved messages\nconst resumed = await generateText({\n  model,\n  tools: m.tools,\n  messages, // includes [APPROVED] tool results\n  maxSteps: 10,\n});\n```\n\n## Tier System\n\n| Tier | Behavior | Use for |\n|------|----------|---------|\n| `auto` | Runs freely, logged to auditLog | Read-only tools, lookups |\n| `draft` | Runs + logged to auditLog | Low-risk writes, tagging |\n| `confirm` | `needsApproval` — stops the loop | Destructive actions, sending messages |\n| `block` | Tool removed from agent entirely | Dangerous tools you want to define but never allow |\n\nResolution order: explicit tiers > `resolve()` function > glob patterns > default (`'confirm'`).\n\n```typescript\nconst m = membrane({\n  tools,\n  tiers: { auto: ['readFile'] },\n  patterns: [\n    { match: 'mcp_*', tier: 'confirm', description: 'All MCP tools need approval' },\n  ],\n  resolve: (name) => name.includes('admin') ? 'block' : undefined,\n  default: 'confirm', // unknown tools require approval (secure by default)\n});\n\n// Debug why a tool got its tier\nimport { explainTier } from '@ai-employee-sdk/core';\nconst info = explainTier('mcp_slack_post', m);\n// { tier: 'confirm', source: 'pattern', description: 'All MCP tools need approval', patternIndex: 0 }\n```\n\n## Types\n\nAll types are exported from `@ai-employee-sdk/core`:\n\n```typescript\nimport type {\n  Tier,\n  TierPattern,\n  TierResolution,\n  MembraneConfig,\n  MembraneResult,\n  AuditEntry,\n  MemoryStore,\n  ModelPricing,\n  CostTrackerConfig,\n  CostSnapshot,\n  CostTrackerResult,\n  PendingApproval,\n  InterruptDecision,\n  InterruptHandle,\n  BudgetConfig,\n  VelocityConfig,\n  HeartbeatConfig,\n  HeartbeatResult,\n  EmployeeAgentConfig,\n} from '@ai-employee-sdk/core';\n```\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md","_rev":"1-04cd89bdc04671ea9cc1906231bcbbfc"}