{"_id":"trustloop","name":"trustloop","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"trustloop","version":"1.0.0","description":"AI governance SDK — intercept, audit, and control AI agent tool calls. Add human-in-the-loop approval, kill switches, and a full audit trail to any AI agent.","main":"index.js","types":"types.d.ts","keywords":["ai-governance","ai-agents","mcp","model-context-protocol","openai","anthropic","claude","tool-calls","audit-trail","compliance","human-in-the-loop","kill-switch","eu-ai-act","llm","agent-safety","governance"],"author":{"name":"trustloop_sdk"},"license":"MIT","homepage":"https://trustloop.live","repository":{"type":"git","url":"git+https://github.com/SMJAI/trustloop-sdk.git"},"bugs":{"url":"https://github.com/SMJAI/trustloop-sdk/issues"},"engines":{"node":">=18"},"gitHead":"aaedbd082571010098b7959b945e417996fcd263","_id":"trustloop@1.0.0","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-IMiI41EkDEk0Zz3lMn3HpvRIDHSvBgkv7SAv5ynl+CDDvdLCuhLW2sbKUovJ3lANJVkgZ94X/ctBZ565khJiJw==","shasum":"3c7dee84d30ec071be95c107578afe424b91f492","tarball":"https://registry.npmjs.org/trustloop/-/trustloop-1.0.0.tgz","fileCount":5,"unpackedSize":23256,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCl1Ro5yj2Lu2hBt35jM9jLoXD2B5H/WQYPeXGEHXzLHAIhALVGZpOx8AMQKoj06wzugRpAKPc/IWZQjEItC1H55Ur4"}]},"_npmUser":{"name":"trustloop_sdk","email":"soji@trustloop.live"},"directories":{},"maintainers":[{"name":"trustloop_sdk","email":"soji@trustloop.live"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/trustloop_1.0.0_1772909109682_0.8946975349011657"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-07T18:45:09.681Z","1.0.0":"2026-03-07T18:45:09.852Z","modified":"2026-03-07T18:45:10.050Z"},"maintainers":[{"name":"trustloop_sdk","email":"soji@trustloop.live"}],"description":"AI governance SDK — intercept, audit, and control AI agent tool calls. Add human-in-the-loop approval, kill switches, and a full audit trail to any AI agent.","homepage":"https://trustloop.live","keywords":["ai-governance","ai-agents","mcp","model-context-protocol","openai","anthropic","claude","tool-calls","audit-trail","compliance","human-in-the-loop","kill-switch","eu-ai-act","llm","agent-safety","governance"],"repository":{"type":"git","url":"git+https://github.com/SMJAI/trustloop-sdk.git"},"author":{"name":"trustloop_sdk"},"bugs":{"url":"https://github.com/SMJAI/trustloop-sdk/issues"},"license":"MIT","readme":"# trustloop\n\n**AI governance SDK for Node.js** — add human-in-the-loop approval, kill switches, and a tamper-evident audit trail to any AI agent in minutes.\n\n[![npm version](https://img.shields.io/npm/v/trustloop.svg)](https://www.npmjs.com/package/trustloop)\n[![npm downloads](https://img.shields.io/npm/dm/trustloop.svg)](https://www.npmjs.com/package/trustloop)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n---\n\n## What is TrustLoop?\n\nWhen an AI agent calls a tool — sends an email, writes to a database, approves a wire transfer — TrustLoop intercepts that action **before** it executes, evaluates it against your governance rules, and either:\n\n- **Allows** it (logs to audit trail)\n- **Blocks** it (kill switch or rule match)\n- **Holds it for human approval** (notifies via email, Slack, Teams, or Discord)\n\nWorks with **OpenAI function calling**, **MCP (Model Context Protocol)**, **LangChain**, **CrewAI**, and any agent framework.\n\n---\n\n## Installation\n\n```bash\nnpm install trustloop\n```\n\nRequires Node.js 18+. No dependencies.\n\n---\n\n## Quick Start\n\n### Option A — OpenAI Proxy (2-line change)\n\nPoint your existing OpenAI client at TrustLoop. All tool calls are governed automatically, with zero changes to your agent code.\n\n```js\nimport OpenAI from 'openai';\nimport TrustLoop from 'trustloop';\n\n// Before: new OpenAI({ apiKey: 'sk-...' })\n// After:\nconst client = new OpenAI(\n  TrustLoop.openai('sk-your-openai-key', 'tl_your-trustloop-key')\n);\n\n// Your agent code is unchanged — governance is automatic\nconst response = await client.chat.completions.create({\n  model: 'gpt-4o',\n  messages: [{ role: 'user', content: 'Transfer £50,000 to SG-7731' }],\n  tools: [/* your tools */],\n});\n```\n\nGet your TrustLoop API key at [trustloop.live/signup](https://trustloop.live/signup) — free, no credit card.\n\n---\n\n### Option B — Manual Intercept\n\nCheck each tool call explicitly before running it:\n\n```js\nimport TrustLoop from 'trustloop';\n\nconst tl = new TrustLoop({ apiKey: 'tl_your-key' });\n\nasync function runTool(toolName, args) {\n  const check = await tl.intercept(toolName, args);\n\n  if (check.allowed) {\n    return await yourToolImplementation(toolName, args);\n  }\n\n  if (check.status === 'PENDING') {\n    return `Awaiting human approval (ID: ${check.approval_id})`;\n  }\n\n  throw new Error(`Blocked by TrustLoop: ${check.message}`);\n}\n\n// Usage\nawait runTool('send_email', { to: 'ceo@bank.com', subject: 'Wire Transfer' });\n```\n\n---\n\n### Option C — MCP (Claude Desktop, Cline)\n\nAdd TrustLoop to your Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"trustloop\": {\n      \"url\": \"https://trustloop-production.up.railway.app/sse?api_key=tl_your-key\"\n    }\n  }\n}\n```\n\nOr use the helper:\n\n```js\nimport TrustLoop from 'trustloop';\nconsole.log(TrustLoop.mcpUrl('tl_your-key'));\n// https://trustloop-production.up.railway.app/sse?api_key=tl_your-key\n```\n\n---\n\n## Governance Rules\n\nCreate rules in plain English. TrustLoop's AI evaluates every tool call against your rules in real time.\n\n```js\nconst tl = new TrustLoop({ apiKey: 'tl_your-key' });\n\n// Block a class of tools outright\nawait tl.createRule({\n  rule_text: 'Block all delete_customer_data calls immediately',\n  action: 'block',\n});\n\n// Require human approval for high-value actions\nawait tl.createRule({\n  rule_text: 'Any wire transfer over £1,000 requires human approval',\n  action: 'approve',\n  approver_email: 'cfo@yourcompany.com',\n});\n\n// Require approval for sensitive data exports\nawait tl.createRule({\n  rule_text: 'Any data export with include_pii=true requires approval',\n  action: 'approve',\n});\n```\n\nWhen a rule fires with `action: 'approve'`, the tool call is held and your approver receives an email (plus Slack/Teams/Discord if configured) with one-click **Approve** and **Deny** links.\n\n---\n\n## Kill Switch\n\nInstantly block a tool by name — no rule evaluation, no delay:\n\n```js\n// Emergency block\nawait tl.blockTool('drop_table', 'Emergency: destructive DB operations disabled');\nawait tl.blockTool('delete_all_records');\n\n// List blocked tools\nconst blocked = await tl.getBlockedTools();\n\n// Unblock when safe\nawait tl.unblockTool('drop_table');\n```\n\n---\n\n## Audit Log\n\nEvery tool call is logged permanently with full arguments, status, and which rule matched:\n\n```js\n// Get recent logs\nconst logs = await tl.getLogs({ limit: 100 });\n// [{ tool_name, arguments, status, rule_matched, created_at }, ...]\n\n// Filter by status\nconst blocked = await tl.getLogs({ status: 'BLOCKED' });\n\n// Export as CSV (for compliance)\nconst csv = await tl.exportLogs();\nfs.writeFileSync('audit.csv', csv);\n\n// Get stats\nconst stats = await tl.getStats();\n// { total: 1420, allowed: 1380, blocked: 32, pending: 8, usage: { plan: 'free', used: 1420, limit: 5000 } }\n```\n\n---\n\n## Pending Approvals\n\n```js\n// See what's waiting\nconst pending = await tl.getPendingApprovals();\n\n// Approve or deny programmatically\nawait tl.decide(pending[0].id, 'approved');\nawait tl.decide(pending[1].id, 'denied');\n```\n\n---\n\n## Notifications\n\nConfigure where approval requests are sent:\n\n```js\nawait tl.updateNotifications({\n  notify_email: 'compliance@yourcompany.com',\n  slack_webhook_url: 'https://hooks.slack.com/services/...',\n  teams_webhook_url: 'https://yourcompany.webhook.office.com/...',\n  discord_webhook_url: 'https://discord.com/api/webhooks/...',\n});\n```\n\n---\n\n## Full API Reference\n\n| Method | Description |\n|--------|-------------|\n| `tl.intercept(toolName, args)` | Check a tool call — returns ALLOWED, BLOCKED, or PENDING |\n| `tl.getLogs(options?)` | Fetch audit log entries |\n| `tl.exportLogs()` | Export full audit log as CSV |\n| `tl.getStats()` | Dashboard stats and monthly usage |\n| `tl.getRules()` | List governance rules |\n| `tl.createRule({ rule_text, action, approver_email })` | Create a governance rule |\n| `tl.deleteRule(ruleId)` | Delete a rule |\n| `tl.getBlockedTools()` | List kill-switched tools |\n| `tl.blockTool(toolName, reason?)` | Block a tool immediately |\n| `tl.unblockTool(toolName)` | Remove a tool from the block list |\n| `tl.getPendingApprovals()` | List tool calls awaiting human approval |\n| `tl.decide(approvalId, action)` | Approve or deny programmatically |\n| `tl.getNotifications()` | Get notification settings |\n| `tl.updateNotifications(settings)` | Update notification channels |\n| `TrustLoop.openai(openaiKey, tlKey)` | Get config for OpenAI client |\n| `TrustLoop.mcpUrl(tlKey)` | Get MCP SSE URL for Claude Desktop |\n\n---\n\n## Error Handling\n\n```js\nimport TrustLoop, { TrustLoopError } from 'trustloop';\n\ntry {\n  const result = await tl.intercept('send_email', { to: '...' });\n} catch (err) {\n  if (err instanceof TrustLoopError) {\n    console.error(`TrustLoop API error ${err.status}: ${err.message}`);\n  }\n}\n```\n\n---\n\n## TypeScript\n\nFull TypeScript support included — no `@types` package needed.\n\n```ts\nimport TrustLoop, { InterceptResult, Rule, Stats } from 'trustloop';\n\nconst tl = new TrustLoop({ apiKey: 'tl_your-key' });\nconst result: InterceptResult = await tl.intercept('my_tool', { param: 'value' });\n```\n\n---\n\n## Why TrustLoop?\n\n| | LangSmith / Arize | TrustLoop |\n|---|---|---|\n| What it monitors | LLM API layer (what the model said) | Tool execution layer (what the agent **did**) |\n| Kill switch | No | Yes |\n| Human approval workflow | No | Yes |\n| Blockchain audit trail | No | Yes |\n| EU AI Act compliance | No | Yes |\n| Works with any agent framework | No | Yes |\n\n---\n\n## Links\n\n- **Sign up free:** [trustloop.live/signup](https://trustloop.live/signup)\n- **Dashboard:** [app.trustloop.live](https://app.trustloop.live)\n- **Docs:** [trustloop.live/docs](https://trustloop.live/docs)\n- **Website:** [trustloop.live](https://trustloop.live)\n\n---\n\n## License\n\nMIT © [TrustLoop Ltd](https://trustloop.live)\n","readmeFilename":"README.md","_rev":"1-dd4aaf120eaf4b0a4e9b20238a3c8abb"}