{"_id":"@aithericon/hpi","_rev":"5-70b054be7c55dd7dbbd811bee8f2ca4f","name":"@aithericon/hpi","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.0":{"name":"@aithericon/hpi","version":"0.1.0","_id":"@aithericon/hpi@0.1.0","maintainers":[{"name":"milanender","email":"ender@aithericon.com"}],"bin":{"hpi":"dist/bin.js"},"dist":{"shasum":"ae040fcaeb477fece147fd49d141a631407c4d23","tarball":"https://registry.npmjs.org/@aithericon/hpi/-/hpi-0.1.0.tgz","fileCount":20,"integrity":"sha512-p/AECklt7AsAAVYt8JxSFU8r2JMlosFMOWANnoK7CWd7h2iqT1YppoGM0+OAMwYUkThoiLth+WS9F0rlJvQC8g==","signatures":[{"sig":"MEYCIQC8puPGz+lsfimI04mo36vWLPUtKXe+l73AzvGs6izhHwIhAMuB28MBx8W1J6qqVoque+uJSphxgt/HPZ4eo2udyj7W","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":188576},"main":"dist/mcp/client.js","type":"module","types":"./dist/mcp/client.d.ts","engines":{"node":">=18.3.0"},"exports":{".":"./dist/mcp/client.js","./client":"./dist/mcp/client.js"},"gitHead":"64e6d38005ddae82746f374e878e6c6f7727af88","scripts":{"dev":"tsup --watch","test":"vitest --run","build":"tsup","test:watch":"vitest"},"_npmUser":{"name":"milanender","email":"ender@aithericon.com"},"_npmVersion":"10.9.2","description":"Human-in-the-loop tasks for AI agents — MCP server + CLI","directories":{},"_nodeVersion":"22.16.0","dependencies":{"@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^4.0.18","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/hpi_0.1.0_1772187148988_0.09046819053432142","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aithericon/hpi","version":"0.1.1","_id":"@aithericon/hpi@0.1.1","maintainers":[{"name":"milanender","email":"ender@aithericon.com"}],"bin":{"hpi":"dist/bin.js"},"dist":{"shasum":"4be18da466218a6122972327d436f592241d6370","tarball":"https://registry.npmjs.org/@aithericon/hpi/-/hpi-0.1.1.tgz","fileCount":21,"integrity":"sha512-5zZi7ZnIhRUYsRmhrPqgbT5Rl2z9e2WzGs+R+IpcLeSi60TafwgVtuJ0A9zHtEeTJlVGbXA8l4zfvw2xknfiKw==","signatures":[{"sig":"MEQCIDVkMtRFXutVch0gkA+ira9PsMnWpGt5mFeV25PIoI63AiAOfjp8NtcxRWnLV1hMEUbfDGvRg73QP9Sso3+ViNXwEw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":203965},"main":"dist/mcp/client.js","type":"module","types":"./dist/mcp/client.d.ts","engines":{"node":">=18.3.0"},"exports":{".":"./dist/mcp/client.js","./client":"./dist/mcp/client.js"},"gitHead":"da9b60a4bc3ae3cce6e7ddba1423b75218d70d1d","scripts":{"dev":"tsup --watch","test":"vitest --run","build":"tsup","test:watch":"vitest"},"_npmUser":{"name":"milanender","email":"ender@aithericon.com"},"_npmVersion":"10.9.2","description":"Human-in-the-loop tasks for AI agents — MCP server + CLI","directories":{},"_nodeVersion":"22.16.0","dependencies":{"@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^4.0.18","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/hpi_0.1.1_1772272734673_0.9795868697361931","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@aithericon/hpi","version":"0.1.2","keywords":["human-in-the-loop","mcp","ai-agents","task-management","model-context-protocol"],"author":{"name":"Aithericon GmbH","email":"hello@aithericon.com"},"license":"Apache-2.0","_id":"@aithericon/hpi@0.1.2","maintainers":[{"name":"milanender","email":"ender@aithericon.com"}],"homepage":"https://hpi.dev","bugs":{"url":"https://github.com/aithericon/hpi/issues"},"bin":{"hpi":"dist/bin.js"},"dist":{"shasum":"485e9679ef2a3efa6e29870d92f296e411a0cf4c","tarball":"https://registry.npmjs.org/@aithericon/hpi/-/hpi-0.1.2.tgz","fileCount":14,"integrity":"sha512-BaSU3/sIzsLjqX8W7MytF2Wx7kUip71XixmiNpQUIsENg0hK2UeYgoKALIg5+b1iapTq/4kjTiagsoz4fbSmRQ==","signatures":[{"sig":"MEUCIQDBAT6dlZPgEkeRqMVUSe0VEKOdDLxetWN+/s/cquEdsQIgKHXMxH4LCLl4qyC07Sl+1BSUggR7nJkDUmryewCembI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":108141},"main":"dist/mcp/client.js","type":"module","types":"dist/mcp/client.d.ts","engines":{"node":">=18.3.0"},"exports":{".":{"types":"./dist/mcp/client.d.ts","import":"./dist/mcp/client.js"},"./client":{"types":"./dist/mcp/client.d.ts","import":"./dist/mcp/client.js"}},"gitHead":"fefd5794740604483aa68ef72e576f7f11163d35","scripts":{"dev":"tsup --watch","test":"vitest --run","build":"tsup","test:watch":"vitest"},"_npmUser":{"name":"milanender","email":"ender@aithericon.com"},"repository":{"url":"git+https://github.com/aithericon/hpi.git","type":"git","directory":"packages/hpi"},"_npmVersion":"10.9.2","description":"Human-in-the-loop tasks for AI agents — MCP server + CLI","directories":{},"_nodeVersion":"22.16.0","dependencies":{"@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^4.0.18","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/hpi_0.1.2_1772446729019_0.021906890372879628","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@aithericon/hpi","version":"0.1.3","keywords":["human-in-the-loop","mcp","ai-agents","task-management","model-context-protocol"],"author":{"name":"Aithericon GmbH","email":"hello@aithericon.com"},"license":"Apache-2.0","_id":"@aithericon/hpi@0.1.3","maintainers":[{"name":"milanender","email":"ender@aithericon.com"}],"homepage":"https://hpi.dev","bugs":{"url":"https://github.com/aithericon/hpi/issues"},"bin":{"hpi":"dist/bin.js"},"dist":{"shasum":"256e432d7dfe84c2149d7adf9497461f2d14bcc4","tarball":"https://registry.npmjs.org/@aithericon/hpi/-/hpi-0.1.3.tgz","fileCount":18,"integrity":"sha512-plcAx1toR9ZY4jAy26Khc/Y1jLURynmTJF3RYrgKb4We6aEhu/o8Edc4vKxD1BQuXpqhZSc2H+o9h5OhQAX+7A==","signatures":[{"sig":"MEUCID4ygPOMFq+wBc3ByWmCn7TclFcKwXtrmBLmUflaZCE8AiEAgwnMQDzQqAKNzehtOTuC4nw0sTL2EEva5t6syk5bAS4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":131471},"main":"dist/mcp/client.js","type":"module","types":"dist/mcp/client.d.ts","engines":{"node":">=18.3.0"},"exports":{".":{"types":"./dist/mcp/client.d.ts","import":"./dist/mcp/client.js"},"./client":{"types":"./dist/mcp/client.d.ts","import":"./dist/mcp/client.js"}},"gitHead":"6227b8e635879d759d24e4f606a66885fa0ba816","scripts":{"dev":"tsup --watch","test":"vitest --run","build":"tsup","test:watch":"vitest"},"_npmUser":{"name":"milanender","email":"ender@aithericon.com"},"repository":{"url":"git+https://github.com/aithericon/hpi.git","type":"git","directory":"packages/hpi"},"_npmVersion":"10.9.2","description":"Human-in-the-loop tasks for AI agents — MCP server + CLI","directories":{},"_nodeVersion":"22.16.0","dependencies":{"@aithericon/hpi":"^0.1.2","@aithericon/hpi-sdk":"^0.1.3","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^4.0.18","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/hpi_0.1.3_1773010350174_0.9944957002155395","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@aithericon/hpi","version":"0.1.4","description":"Human-in-the-loop tasks for AI agents — MCP server + CLI","license":"Apache-2.0","author":{"name":"Aithericon GmbH","email":"hello@aithericon.com"},"homepage":"https://hpi.dev","repository":{"type":"git","url":"git+https://github.com/aithericon/hpi.git","directory":"packages/hpi"},"bugs":{"url":"https://github.com/aithericon/hpi/issues"},"keywords":["human-in-the-loop","mcp","ai-agents","task-management","model-context-protocol"],"type":"module","main":"dist/mcp/client.js","types":"dist/mcp/client.d.ts","exports":{".":{"types":"./dist/mcp/client.d.ts","import":"./dist/mcp/client.js"},"./client":{"types":"./dist/mcp/client.d.ts","import":"./dist/mcp/client.js"}},"bin":{"hpi":"dist/bin.js"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest --run","test:watch":"vitest"},"dependencies":{"@aithericon/hpi-sdk":"^0.1.3","@modelcontextprotocol/sdk":"^1.12.1"},"devDependencies":{"tsup":"^8.4.0","typescript":"^5.9.3","vitest":"^4.0.18"},"engines":{"node":">=18.3.0"},"_id":"@aithericon/hpi@0.1.4","gitHead":"6227b8e635879d759d24e4f606a66885fa0ba816","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-KSNAIgbT+aLYBZHubJnL0yhnJBgPOFwgRJo2AeNDG3QKYgTF4ESIBcDTT6mRdATiZW833wVq7U8WjxEz7MeHQg==","shasum":"b345d3474ce9f4f7b6d6904fb96016c02c468543","tarball":"https://registry.npmjs.org/@aithericon/hpi/-/hpi-0.1.4.tgz","fileCount":18,"unpackedSize":131819,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDnOgERs48EWYX2EdcbmKoc1Zo7rhrRvwfCPoBn9ymz6QIhAK+tMtBsoJUldxguho/qOn37qQ7oj8/3hiZailCf6V25"}]},"_npmUser":{"name":"milanender","email":"ender@aithericon.com"},"directories":{},"maintainers":[{"name":"milanender","email":"ender@aithericon.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hpi_0.1.4_1773011339836_0.8080056167159315"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-27T10:12:28.886Z","modified":"2026-03-08T23:09:00.153Z","0.1.0":"2026-02-27T10:12:29.123Z","0.1.1":"2026-02-28T09:58:54.828Z","0.1.2":"2026-03-02T10:18:49.168Z","0.1.3":"2026-03-08T22:52:30.327Z","0.1.4":"2026-03-08T23:08:59.983Z"},"bugs":{"url":"https://github.com/aithericon/hpi/issues"},"author":{"name":"Aithericon GmbH","email":"hello@aithericon.com"},"license":"Apache-2.0","homepage":"https://hpi.dev","keywords":["human-in-the-loop","mcp","ai-agents","task-management","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/aithericon/hpi.git","directory":"packages/hpi"},"description":"Human-in-the-loop tasks for AI agents — MCP server + CLI","maintainers":[{"name":"milanender","email":"ender@aithericon.com"}],"readme":"# @aithericon/hpi\n\nHuman-in-the-loop tasks for AI agents. One package — MCP server + CLI.\n\nYour AI agent gets a comprehensive set of tools to create tasks, ask questions, collect approvals, upload files, and orchestrate multi-step workflows. Humans complete them through a web dashboard or magic links. Results flow back to the agent in real time.\n\n## Quick Start\n\n```bash\nnpx @aithericon/hpi login\nnpx @aithericon/hpi setup claude-code\n```\n\nRestart your IDE. Done — your agent can now talk to humans.\n\n### What just happened?\n\n1. `hpi login` opened your browser, you signed in (free account), and a token was saved to `~/.hpi/config.json`\n2. `hpi setup claude-code` wrote the MCP server config into `.mcp.json` in your project\n3. When your IDE starts, it runs `npx @aithericon/hpi` which connects to HPI using the saved token\n\n## IDE Setup\n\n```bash\nnpx @aithericon/hpi setup claude-code   # Claude Code\nnpx @aithericon/hpi setup cursor        # Cursor\nnpx @aithericon/hpi setup windsurf      # Windsurf\n```\n\nOr configure manually in your IDE's MCP config:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"human-tasks\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"@aithericon/hpi\"]\n\t\t}\n\t}\n}\n```\n\n## Remote Approvals (Claude Code)\n\nApprove or deny Claude Code's tool calls from your phone or browser — no need to sit at the terminal.\n\n```bash\nnpx @aithericon/hpi setup claude-code --hooks\n```\n\nThis configures Claude Code hooks that route permission requests through HPI:\n\n1. Claude Code asks for permission → terminal dialog appears as usual\n2. After 3 minutes with no response, an HPI task is created\n3. You approve or deny from the HPI dashboard (phone, browser, anywhere)\n4. The decision flows back to Claude Code automatically\n\nIf you respond in the terminal instead, the HPI task is automatically cancelled on the next tool call.\n\n### How cancellation works\n\nClaude Code currently has no hook that fires when you respond to a permission dialog ([GitHub #19628](https://github.com/anthropics/claude-code/issues/19628)). Cleanup is **eventually consistent** — it runs on the next tool call or when the session ends:\n\n- **You respond within 3 minutes** → no HPI task is ever created\n- **You respond after the task is created** → the task is cancelled on the next tool call\n- **You respond via HPI** → Claude Code receives the decision immediately\n\n### Configuration\n\n| Env var | Default | Description |\n|---------|---------|-------------|\n| `HPI_HOOK_DELAY` | `180` | Seconds to wait before creating an HPI task |\n| `HPI_HOOK_WAIT` | `14400` | Max seconds to poll for an HPI response (4 hours) |\n\n## CLI Commands\n\n```\nhpi                         Start MCP server (default, used by IDEs)\nhpi login [--url URL]       Authenticate with cloud or self-hosted instance\nhpi logout                  Remove stored credentials\nhpi setup <ide>             Configure IDE MCP settings (project-scoped)\nhpi setup <ide> --global    Configure IDE MCP settings (global/user-wide)\nhpi setup <ide> --hooks     Also configure remote approval hooks (claude-code only)\nhpi status                  Show current connection info\n```\n\n## Self-Hosted\n\nConnect to your own instance instead of the cloud:\n\n```bash\nnpx @aithericon/hpi login --url https://hpi.yourcompany.com\n```\n\nOr set environment variables (useful in CI/server contexts):\n\n```bash\nexport HPI_URL=https://hpi.yourcompany.com\nexport HPI_TOKEN=htk_your-api-token\n```\n\n## MCP Tools\n\nOnce connected, your AI agent can use these tools:\n\n| Tool                    | What it does                                                         |\n| ----------------------- | -------------------------------------------------------------------- |\n| `create_task`           | Create a task with steps, fields, and blocks                         |\n| `ask_question`          | Ask a human a free-text question and wait for the answer             |\n| `ask_approval`          | Request yes/no approval with optional details                        |\n| `ask_choice`            | Present multiple options and get a selection                         |\n| `ask_for_review`        | Show content for review with verdict + feedback                      |\n| `send_image`            | Upload and show an image, collect feedback                           |\n| `send_document`         | Upload a document (PDF inline viewer), collect feedback              |\n| `get_task`              | Get task status, completion data, and optionally the full definition |\n| `wait_for_task`         | Block until a task is completed/failed/cancelled                     |\n| `list_tasks`            | List tasks with optional filters                                     |\n| `cancel_task`           | Cancel a pending task                                                |\n| `send_reminder`         | Re-send notification to assignee                                     |\n| `create_task_from_file` | Create a task from a JSON file definition on disk                    |\n| `begin_task`            | Start building a multi-block task                                    |\n| `add_md`                | Add markdown to a draft task                                         |\n| `add_image`             | Add an image to a draft task                                         |\n| `add_file`              | Add a file to a draft task                                           |\n| `add_input`             | Add a form field to a draft task                                     |\n| `add_callout`           | Add an alert/callout to a draft task                                 |\n| `add_table`             | Add a data table to a draft task                                     |\n| `submit_task`           | Submit a draft task and wait for completion                          |\n| `create_process`        | Create a tracked multi-step process                                  |\n| `list_processes`        | List processes with optional filters                                 |\n| `get_process`           | Get process state and timeline                                       |\n| `update_process`        | Push step transitions and progress updates                           |\n\n## Programmatic Usage\n\n```typescript\nimport { HPIClient } from '@aithericon/hpi/client';\n\nconst client = new HPIClient('https://app.hpi.dev', 'htk_your-token');\n\nconst task = await client.createTask({\n\ttitle: 'Review deployment plan',\n\tsteps: [\n\t\t{\n\t\t\tid: 'review',\n\t\t\ttitle: 'Review',\n\t\t\tblocks: [\n\t\t\t\t{ type: 'mdsvex', content: 'Please review the deployment plan for **v2.1**.' },\n\t\t\t\t{ type: 'input', field: { name: 'approved', label: 'Approve?', kind: 'checkbox' } }\n\t\t\t]\n\t\t}\n\t]\n});\n\n// Wait for the human to complete it\nconst result = await client.waitForTask(task.task_id);\nconsole.log(result.data); // { approved: true }\n```\n\n## License\n\n[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)\n","readmeFilename":"README.md"}