{"_id":"@azmxailabs/agent-sdk","_rev":"2-14491bb9eebfa8e1dd346c5bba963a69","name":"@azmxailabs/agent-sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@azmxailabs/agent-sdk","version":"0.1.0","keywords":["azmx","azmx-ai","azmxai","azmxailabs","agent","ai-agent","agent-sdk","approval-gate","byok","anthropic","openai","ollama","audit-log","deny-list","sovereign-ai","local-ai"],"license":"MIT","_id":"@azmxailabs/agent-sdk@0.1.0","maintainers":[{"name":"azmxaiofficial","email":"drewgenaiarch@gmail.com"}],"homepage":"https://azmx.ai","bugs":{"url":"https://github.com/AzmxAI/azmx/issues"},"dist":{"shasum":"f28ac84901700393bcb69c1f41640343c4e89fcf","tarball":"https://registry.npmjs.org/@azmxailabs/agent-sdk/-/agent-sdk-0.1.0.tgz","fileCount":29,"integrity":"sha512-Jslbyeo9Mo6YRZzjiIq56M2Ie+wt+Z/uVipNJJcZPpp6KHg10FguKKRtVnluUtYo4JGxYSiy9Y2IH61Q+O94ow==","signatures":[{"sig":"MEUCIQC9p86TNqlBJ9dYsk7zYYA8zslkDh3H5Jbwbxh1R1XRpwIgS7XC9ZTbHtGewvq9+5OeOaOf6g2YEHKiHgcHTPusvKg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55801},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./audit":{"types":"./dist/audit/index.d.ts","import":"./dist/audit/index.js"},"./approval":{"types":"./dist/approval/index.d.ts","import":"./dist/approval/index.js"},"./security":{"types":"./dist/security/index.d.ts","import":"./dist/security/index.js"},"./providers":{"types":"./dist/providers/index.d.ts","import":"./dist/providers/index.js"}},"gitHead":"29b4b2da8a6eac7c6de6ff9a746148e301445413","scripts":{"dev":"tsc -p tsconfig.json --watch","test":"node --test dist/**/*.test.js","build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"azmxaiofficial","email":"drewgenaiarch@gmail.com"},"repository":{"url":"git+https://github.com/AzmxAI/azmx.git","type":"git","directory":"packages/agent-sdk"},"_npmVersion":"11.12.1","description":"Build approval-gated AI agents with the same primitives that power AZMX AI — BYOK provider router, approval gate, deny-list, hash-chained audit log. Secure by default, BYOK direct (no proxy), no telemetry.","directories":{},"_nodeVersion":"25.9.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.3","@types/node":"^20.14.10"},"_npmOperationalInternal":{"tmp":"tmp/agent-sdk_0.1.0_1779761264522_0.8628720114894008","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@azmxailabs/agent-sdk","version":"0.2.0","description":"Build approval-gated AI agents with the same primitives that power AZMX AI — BYOK provider router (Anthropic / OpenAI / any OpenAI-compatible incl. local REVA & Ollama), approval gate, deny-list, hash-chained audit log. Ships a headless `azmx` CLI. Secure","license":"MIT","type":"module","bin":{"azmx":"dist/cli.js"},"homepage":"https://azmx.ai","repository":{"type":"git","url":"git+https://github.com/AzmxAI/azmx.git","directory":"packages/agent-sdk"},"bugs":{"url":"https://github.com/AzmxAI/azmx/issues"},"keywords":["azmx","azmx-ai","azmxai","azmxailabs","agent","ai-agent","agent-sdk","approval-gate","byok","anthropic","openai","ollama","audit-log","deny-list","sovereign-ai","local-ai"],"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./approval":{"types":"./dist/approval/index.d.ts","import":"./dist/approval/index.js"},"./security":{"types":"./dist/security/index.d.ts","import":"./dist/security/index.js"},"./audit":{"types":"./dist/audit/index.d.ts","import":"./dist/audit/index.js"},"./providers":{"types":"./dist/providers/index.d.ts","import":"./dist/providers/index.js"}},"engines":{"node":">=18"},"scripts":{"build":"tsc -p tsconfig.json","dev":"tsc -p tsconfig.json --watch","clean":"rm -rf dist","test":"node --test dist/**/*.test.js","prepublishOnly":"npm run clean && npm run build"},"dependencies":{},"devDependencies":{"@types/node":"^20.14.10","typescript":"^5.5.3"},"gitHead":"27f4a959464e5bf68d5f1e1c666f7f8d9857f4fd","_id":"@azmxailabs/agent-sdk@0.2.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-8/qKZ1f2s+166t83yxXOnV4+70hr28UtqIMxsxoaAChoAloNVShq2sur8KSVx6YeiwhTNN4c74LOp8PJpWpwFA==","shasum":"62f024cfede1d9687d31b44423a2ff9cf240f4b6","tarball":"https://registry.npmjs.org/@azmxailabs/agent-sdk/-/agent-sdk-0.2.0.tgz","fileCount":33,"unpackedSize":69548,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAOTxpvup8M0UZiNkNUNUNvkRdYEWvcGBvat6KDgtlnvAiBG2QzSryrGDVns3jJYRRsOJb00AwubQ5XjRebtIq1KFg=="}]},"_npmUser":{"name":"azmxaiofficial","email":"drewgenaiarch@gmail.com"},"directories":{},"maintainers":[{"name":"azmxaiofficial","email":"drewgenaiarch@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-sdk_0.2.0_1782946367715_0.41765531441477766"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-26T02:07:44.407Z","modified":"2026-07-01T22:52:48.009Z","0.1.0":"2026-05-26T02:07:44.675Z","0.2.0":"2026-07-01T22:52:47.858Z"},"bugs":{"url":"https://github.com/AzmxAI/azmx/issues"},"license":"MIT","homepage":"https://azmx.ai","keywords":["azmx","azmx-ai","azmxai","azmxailabs","agent","ai-agent","agent-sdk","approval-gate","byok","anthropic","openai","ollama","audit-log","deny-list","sovereign-ai","local-ai"],"repository":{"type":"git","url":"git+https://github.com/AzmxAI/azmx.git","directory":"packages/agent-sdk"},"description":"Build approval-gated AI agents with the same primitives that power AZMX AI — BYOK provider router (Anthropic / OpenAI / any OpenAI-compatible incl. local REVA & Ollama), approval gate, deny-list, hash-chained audit log. Ships a headless `azmx` CLI. Secure","maintainers":[{"name":"azmxaiofficial","email":"drewgenaiarch@gmail.com"}],"readme":"# @azmxailabs/agent-sdk\n\n> Build approval-gated AI agents with the same primitives that power **[AZMX AI](https://azmx.ai)** — BYOK provider router, approval gate, deny-list, hash-chained audit log. Secure by default. BYOK direct (no proxy). No telemetry.\n\n```bash\nnpm install @azmxailabs/agent-sdk\n```\n\n## Why this exists\n\nMost \"AI agent\" frameworks bolt safety on as middleware. AZMX builds it in. This SDK ships the four primitives that make that possible as standalone, dependency-free TypeScript so you can use them in your own agent — whether that's a CI script, a CLI, a desktop app, or a server.\n\n- **Approval gate** — every side-effecting action passes through a configurable policy chain before it runs.\n- **Deny-list** — refuses `.env`, `.ssh`, credentials, and any other path you care about by glob.\n- **Hash-chained audit log** — every entry includes the previous entry's hash; tampering breaks the chain detectably.\n- **Provider router** — one ergonomic interface across Anthropic, Ollama, and any other backend you plug in.\n\nZero runtime dependencies. Node ≥ 18. ESM.\n\n## Quick start\n\n```ts\nimport {\n  ApprovalGate,\n  standardPolicy,\n  destructiveShellDenyPolicy,\n  DenyList,\n  denyListPolicy,\n  HashChainedAuditLog,\n  ProviderRouter,\n  AnthropicProvider,\n  OllamaProvider,\n} from \"@azmxailabs/agent-sdk\";\n\n// 1. Audit log (hash-chained, tamper-evident)\nconst log = new HashChainedAuditLog({ path: \"./agent-audit.jsonl\" });\n\n// 2. Deny-list (refuses sensitive paths)\nconst deny = new DenyList(); // ships with sensible defaults\n\n// 3. Approval gate (the heart of the safety model)\nconst gate = new ApprovalGate({\n  policies: [\n    denyListPolicy(deny),\n    destructiveShellDenyPolicy(),\n    standardPolicy(),\n  ],\n  onPrompt: async ({ action, reasons }) => {\n    // Your UI shows the action; user picks. Reasons = the policies that asked.\n    console.log(`\\n[approval needed] ${action.kind}: ${action.summary}`);\n    console.log(`reasons: ${reasons.join(\", \")}`);\n    // Real code: prompt the user. Here we auto-approve for the example.\n    return \"approve\";\n  },\n  onDecision: (event) => log.append({ type: \"approval\", ...event }),\n});\n\n// 4. Provider router (BYOK — direct, no proxy)\nconst router = new ProviderRouter()\n  .register(\"claude\", new AnthropicProvider({\n    apiKey: process.env.ANTHROPIC_API_KEY!,\n    model: \"claude-opus-4-7\",\n  }))\n  .register(\"local\", new OllamaProvider({ model: \"qwen2.5-coder:14b\" }));\n\n// Use it\nconst decision = await gate.check({\n  kind: \"shell\",\n  summary: \"ls -la /tmp\",\n  target: \"/tmp\",\n});\n\nif (decision === \"approved\") {\n  const result = await router.complete({\n    model: \"claude\",\n    messages: [{ role: \"user\", content: \"Summarize what `ls -la` shows.\" }],\n  });\n  console.log(result.text);\n}\n\n// Verify the audit log later\nconst verification = await log.verify();\nif (!verification.ok) {\n  console.error(\"Audit log tampered at seq\", verification.brokenAtSeq);\n}\n```\n\n## API\n\n### `ApprovalGate`\n\nEvery side-effecting action passes through here. Policies vote (`auto` / `ask` / `deny`); most-restrictive wins.\n\n```ts\nconst gate = new ApprovalGate({\n  policies: [denyListPolicy(), destructiveShellDenyPolicy(), standardPolicy()],\n  onPrompt: async ({ action, reasons }) => \"approve\" | \"approve-and-trust\" | \"reject\",\n  onDecision: (event) => auditLog.append(event), // optional sink\n});\n\nconst decision = await gate.check({\n  kind: \"shell\" | \"file:write\" | \"file:read\" | \"file:delete\" | \"network\" | \"git\" | \"process:spawn\" | \"tool\" | (string & {}),\n  summary: \"human-readable one-liner\",\n  target: \"/path or URL\",\n  payload: anyObject, // optional structured verb\n});\n// → \"approved\" | \"denied\"\n```\n\n**Built-in policies** (importable from `@azmxailabs/agent-sdk/approval`):\n\n| Policy | Behavior |\n|---|---|\n| `standardPolicy()` | The AZMX default. Reads auto; writes / deletes / shell / spawns ask; destructive shell verbs always ask. |\n| `paranoidPolicy()` | Asks for everything — even reads. For untrusted code, classified work, compliance demos. |\n| `permissivePolicy()` | Auto-approves everything. For trusted CI agents with their own external guardrails. |\n| `destructiveShellDenyPolicy(extra?)` | Hard-blocks `rm`, `dd`, `shutdown`, etc. — no prompt. Adds your verbs to the list. |\n\n### `DenyList` + `denyListPolicy`\n\n```ts\nimport { DenyList, DEFAULT_DENY_LIST, denyListPolicy } from \"@azmxailabs/agent-sdk/security\";\n\nconst deny = new DenyList(); // defaults: .env, .ssh, credentials, .aws/credentials, .kube/config, cookies, keychain files, ...\ndeny.add(\"**/proprietary/**\");\ndeny.matches(\"/Users/me/.ssh/id_rsa\"); // true\ndeny.matching(\"/Users/me/.ssh/id_rsa\"); // [\"**/.ssh/**\", \"**/id_rsa\"]\n\n// Plug into the gate:\nconst policy = denyListPolicy(deny);\n```\n\nGlobs: `*` (any chars except `/`), `**` (any chars), `?` (single char), `[abc]` (char class).\n\n### `HashChainedAuditLog`\n\nAppend-only log where each entry's hash includes the previous entry's hash. Tampering with any past entry breaks the chain.\n\n```ts\nimport { HashChainedAuditLog, FileStorage, InMemoryStorage } from \"@azmxailabs/agent-sdk/audit\";\n\nconst log = new HashChainedAuditLog({ path: \"./audit.jsonl\" }); // FileStorage by default\nawait log.append({ type: \"shell\", cmd: \"ls -la /tmp\" });\nawait log.append({ type: \"approval\", decision: \"approve\" });\n\nconst v = await log.verify();\n// v.ok === true  → all entries valid\n// v.ok === false → { brokenAtSeq, reason, expected?, found? }\n```\n\nGenesis prevHash = 64 zero bytes. Each entry's hash = `sha256(JSON.stringify({seq, ts, prevHash, data}))`. File mode is 0600.\n\n### `ProviderRouter`\n\n```ts\nimport {\n  ProviderRouter,\n  AnthropicProvider,\n  OllamaProvider,\n} from \"@azmxailabs/agent-sdk/providers\";\n\nconst router = new ProviderRouter()\n  .register(\"claude-fast\", new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY!, model: \"claude-haiku-4-5\" }))\n  .register(\"claude-smart\", new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY!, model: \"claude-opus-4-7\" }))\n  .register(\"local\", new OllamaProvider({ model: \"qwen2.5-coder:14b\" }));\n\nconst r = await router.complete({\n  model: \"claude-fast\",\n  messages: [\n    { role: \"system\", content: \"You are concise.\" },\n    { role: \"user\", content: \"Hello\" },\n  ],\n  temperature: 0.2,\n  maxTokens: 200,\n});\nconsole.log(r.text, r.usage);\n\n// Streaming\nfor await (const chunk of router.stream({ model: \"local\", messages: [...] })) {\n  process.stdout.write(chunk.delta);\n  if (chunk.done) console.log(\"\\n[finishReason]\", chunk.finishReason);\n}\n```\n\n**Built-in adapters:**\n\n| Adapter | API | BYOK / local |\n|---|---|---|\n| `AnthropicProvider` | POST `/v1/messages` | BYOK direct |\n| `OllamaProvider` | POST `/api/chat` | Local |\n\n**Adding your own:** implement the `Provider` interface — `name`, `complete`, `stream`. ~50 lines of code per provider; see `src/providers/ollama.ts` for a minimal reference.\n\n## Design choices\n\n- **No runtime dependencies.** Provider adapters call HTTP via `fetch` directly. Adding the official SDK for any provider is a 5-line wrapper at most — but the SDK doesn't need it.\n- **Approval is the first-class concept.** Every other primitive plugs into the gate (deny-list → policy; audit log → onDecision sink). The brand-DNA path is \"gate then act.\"\n- **BYOK direct.** Provider adapters take an `apiKey` and call the provider's own endpoint. AZMX servers never see your prompts or tokens.\n- **Audit log is tamper-evident, not tamper-proof.** Hash chains prove that something changed — they don't prevent change. Pair with append-only storage (immutable S3 bucket, WORM volume) for hard guarantees.\n\n## Roadmap (v0.2+)\n\n- Tool / function-calling support across the provider interface\n- `OpenAIProvider` (covers OpenAI + most OpenAI-compatible APIs: Groq, Cerebras, xAI, DeepSeek, Azure, NVIDIA NIM)\n- `GoogleProvider` (Gemini)\n- An `MCPClient` for talking to MCP servers (`@modelcontextprotocol/sdk` wrapper)\n- Streaming tool calls\n- Cost tracking middleware\n\nFile an issue at https://github.com/AzmxAI/azmx/issues if you want any of these prioritized — or open a PR.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\n## About AZMX AI\n\nAZMX AI is a native AI coding agent that runs on your machine, with your keys (BYOK across 11+ providers, or fully offline via Ollama / LM Studio). Every write is gated by per-call approval. No account, no telemetry. Free forever for individuals.\n\n- Homepage: https://azmx.ai\n- Docs: https://azmx.ai/docs\n- MCP server: https://www.npmjs.com/package/@azmxailabs/mcp\n- Source: https://github.com/AzmxAI/azmx\n","readmeFilename":"README.md"}