@vess-id/vess 0.2.0-alpha.1

package/LICENSE

@@ -0,0 +1,64 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             VESS Labs
+Licensed Work:        @vess-id/vess v0.1.0
+                      The Licensed Work is (c) 2025 VESS Labs.
+Additional Use Grant: You may use the Licensed Work for any purpose,
+                      including production use, as a command-line tool
+                      installed via npm. You may not use the Licensed Work
+                      to provide a managed service or hosted offering that
+                      competes with the Licensed Work or any other product
+                      or service offered by the Licensor.
+Change Date:          2030-03-23
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact info@vess.id.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/README.md

@@ -0,0 +1,223 @@
+# @vess-id/vess
+
+> Local AI agent runtime — manages identity, permissions, and execution boundaries for AI coding agents.
+
+## What is VESS?
+
+VESS (Verifiable Execution Sandbox for Software agents) is a local runtime that gives your AI coding agent a cryptographic identity and enforces security boundaries on your machine.
+
+- **Creates a DID-based cryptographic identity** for your development machine, stored securely in the OS Keychain
+- **Registers as an MCP (Model Context Protocol) server** in Claude Code, so the agent operates within VESS-managed boundaries
+- **Enforces policies** to protect sensitive files (`.ssh`, `.aws`, `.gnupg`) from unintended access
+- **Manages environment variable secrets** via OS Keychain with Touch ID protection — secrets never sit in plaintext on disk
+- **Connects to the VESS gateway** for project management and credential issuance
+
+## Beta Status
+
+This is a **beta release** (v0.1.0).
+
+| Platform | Status |
+|----------|--------|
+| **macOS + Claude Code** | Primary target, fully supported |
+| **Linux** | Daemon/service support exists but not fully tested |
+| **Windows** | Not supported |
+
+## Prerequisites
+
+- **Node.js 22** or later
+- **macOS** (primary) or Linux
+- **Claude Code** — [installation guide](https://docs.anthropic.com/en/docs/claude-code)
+- **A VESS account** — sign up at [app.vess.id](https://app.vess.id)
+
+## Getting Started
+
+### Step 1: Sign Up
+
+1. Create an account at [https://app.vess.id](https://app.vess.id)
+2. Create a project
+3. (Optional) Connect integrations: Slack, Google Calendar, Jira
+
+### Step 2: Install & Initialize
+
+```bash
+npm install -g @vess-id/vess
+vess init
+```
+
+This single command will:
+
+- Generate a cryptographic identity (DID) for your device
+- Open a browser for device verification
+- Install a background daemon (auto-starts on login, localhost only)
+- Register VESS as an MCP server in Claude Code
+
+### Step 3: Verify
+
+Restart Claude Code, then:
+
+```bash
+vess status
+```
+
+## Commands
+
+### Core
+
+| Command | Description |
+|---------|-------------|
+| `vess init` | Initialize device + daemon + MCP registration (all-in-one) |
+| `vess init --no-daemon` | Initialize without daemon (stdio mode only) |
+| `vess init --no-install` | Initialize without Claude Code MCP registration |
+| `vess init --force` | Force re-initialization even if already set up |
+| `vess login` | Re-authenticate after session expiry |
+| `vess status` | Show runtime status (auth, daemon, wallet) |
+| `vess doctor` | Diagnose setup issues |
+| `vess uninstall` | Completely remove VESS (MCP, daemon, config, keychain) |
+
+### MCP Registration
+
+| Command | Description |
+|---------|-------------|
+| `vess mcp register` | Register VESS as an MCP server in Claude Code |
+
+> Tip: `vess init` runs this automatically. Use `vess mcp register` only if you skipped MCP registration during init or need to re-register after manual removal.
+
+### Daemon
+
+| Command | Description |
+|---------|-------------|
+| `vess daemon start` | Start the daemon (default: `127.0.0.1:3100`) |
+| `vess daemon start --foreground` | Run in foreground (no daemonization) |
+| `vess daemon stop` | Stop the running daemon |
+| `vess daemon enable` | Enable auto-start on login (installs OS service) |
+| `vess daemon disable` | Disable auto-start (removes OS service) |
+
+### Logs
+
+| Command | Description |
+|---------|-------------|
+| `vess logs` | Show recent daemon output (default: 50 lines) |
+| `vess logs --follow` | Stream logs in real-time |
+| `vess logs --lines 100` | Show last 100 lines |
+
+### Projects
+
+| Command | Description |
+|---------|-------------|
+| `vess project list` | List available projects |
+| `vess project use <id>` | Switch active project |
+| `vess project sync` | Re-fetch projects from gateway |
+
+### Environment Secrets
+
+| Command | Description |
+|---------|-------------|
+| `vess env import <file> --profile <name>` | Import .env into a secure profile |
+| `vess env list` | List profiles and stored keys |
+| `vess env list --profile <name>` | Show keys for a specific profile |
+| `vess env delete --profile <name>` | Remove secrets from keychain |
+| `vess env delete --profile <name> --keys <k1,k2>` | Remove specific keys only |
+| `vess env restore --profile <name>` | Decrypt and restore .env (requires Touch ID) |
+| `vess env restore --profile <name> --output <path>` | Write restored .env to a file |
+| `vess run -- <command>` | Run command with decrypted env injection |
+
+**`env import` options:**
+
+| Flag | Description |
+|------|-------------|
+| `--interactive` | Classify each variable interactively |
+| `--all-secret` | Treat all variables as secrets |
+| `--keys <k1,k2>` | Specify which keys are secrets (rest are plaintext) |
+| `--plaintext-keys <k1,k2>` | Specify additional plaintext keys (used with default mode) |
+| `--dry-run` | Preview classification without making changes |
+| `--skip-integration` | Skip post-import integration steps (package.json, CLAUDE.md, hooks) |
+
+> Note: `--interactive`, `--all-secret`, and `--keys` are mutually exclusive.
+
+**`run` options:**
+
+| Flag | Description |
+|------|-------------|
+| `--profile <name>` | Env profile name (for logging) |
+| `--cwd <dir>` | Working directory |
+| `--timeout <seconds>` | Timeout in seconds |
+
+## What Works in Beta
+
+- Device identity creation (DID key pair, OS Keychain storage)
+- Device enrollment via browser-based verification
+- MCP server registration in Claude Code (stdio + HTTP daemon)
+- Environment variable management with OS Keychain-backed secrets
+- Touch ID-gated secret access (macOS)
+- Policy enforcement (deny rules for `~/.ssh`, `~/.aws`, `~/.gnupg`)
+- Project management (list, switch, sync)
+- Audit logging
+- OS service integration (launchd on macOS, systemd on Linux)
+
+## Known Limitations
+
+- Web dashboard signup and project creation required before CLI use
+- No team/org-level policy sharing yet
+- No automatic credential rotation
+- Session tokens expire — run `vess login` to re-authenticate
+- `vess env import --interactive` mode is experimental
+- Daemon auto-start is set up during `vess init`; run `vess daemon enable` to re-enable if disabled
+
+## How It Works
+
+```
+┌─────────────┐     MCP Protocol     ┌──────────────┐
+│ Claude Code  │ <──────────────────> │  VESS agentd │
+└─────────────┘    (stdio or HTTP)    └──────┬───────┘
+                                             │
+                                    ┌────────┼────────┐
+                                    │        │        │
+                               ┌────▼──┐ ┌──▼───┐ ┌──▼────┐
+                               │Policy │ │Wallet│ │Keychain│
+                               │Engine │ │ (DB) │ │ (OS)  │
+                               └───────┘ └──┬───┘ └───────┘
+                                            │
+                                     ┌──────▼──────┐
+                                     │VESS Gateway │
+                                     │(api.vess.id)│
+                                     └─────────────┘
+```
+
+## Data Storage
+
+All data stored under `~/.vess/`:
+
+| File | Purpose |
+|------|---------|
+| `config.json` | Gateway URL, root DID, default project |
+| `policy.json` | Local deny rules |
+| `wallet.db` | SQLite — credentials, projects, audit logs |
+| `logs/` | Audit log directory |
+
+Secrets (root key, session token, env values) are stored in the **OS Keychain**, not on disk.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Not initialized" | Run `vess init` |
+| "No projects found" | Create one at [app.vess.id/projects](https://app.vess.id/projects), then `vess project sync` |
+| Session expired | Run `vess login` |
+| Claude Code doesn't see VESS | Run `vess mcp register`, restart Claude Code |
+| Daemon not starting | Check `vess logs`, try `vess daemon start --foreground` |
+| Need a fresh start | Run `vess uninstall`, then `vess init` |
+| Diagnose issues | Run `vess doctor` |
+
+## Links
+
+- **Web Dashboard:** [https://app.vess.id](https://app.vess.id)
+- **Documentation:** [https://vess.id/docs](https://vess.id/docs)
+- **GitHub:** [https://github.com/cvoxelprotocol/aidentity](https://github.com/cvoxelprotocol/aidentity)
+
+## Support
+
+For bug reports, feature requests, or questions, please contact us at info@vess.id
+
+## License
+
+Business Source License 1.1 — see [LICENSE](./LICENSE) for details.

package/bin/vess.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli/index.js')

package/dist/__mocks__/@napi-rs/keyring.d.ts

@@ -0,0 +1,9 @@
+export declare function _clearStore(): void;
+export declare class Entry {
+    private readonly key;
+    constructor(service: string, name: string);
+    setPassword(password: string): void;
+    getPassword(): string;
+    deletePassword(): void;
+}
+//# sourceMappingURL=keyring.d.ts.map

package/dist/__mocks__/@napi-rs/keyring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyring.d.ts","sourceRoot":"","sources":["../../../src/__mocks__/@napi-rs/keyring.ts"],"names":[],"mappings":"AAGA,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;gBAEhB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAIzC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAInC,WAAW,IAAI,MAAM;IAQrB,cAAc,IAAI,IAAI;CAMvB"}

package/dist/__mocks__/@napi-rs/keyring.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Entry = void 0;
+exports._clearStore = _clearStore;
+// Manual mock for @napi-rs/keyring — used in tests without OS keychain access
+const store = new Map();
+function _clearStore() {
+    store.clear();
+}
+class Entry {
+    key;
+    constructor(service, name) {
+        this.key = `${service}:${name}`;
+    }
+    setPassword(password) {
+        store.set(this.key, password);
+    }
+    getPassword() {
+        const val = store.get(this.key);
+        if (val === undefined) {
+            throw new Error('No password found');
+        }
+        return val;
+    }
+    deletePassword() {
+        if (!store.has(this.key)) {
+            throw new Error('No password found');
+        }
+        store.delete(this.key);
+    }
+}
+exports.Entry = Entry;
+//# sourceMappingURL=keyring.js.map

package/dist/__mocks__/@napi-rs/keyring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyring.js","sourceRoot":"","sources":["../../../src/__mocks__/@napi-rs/keyring.ts"],"names":[],"mappings":";;;AAGA,kCAEC;AALD,8EAA8E;AAC9E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAA;AAEvC,SAAgB,WAAW;IACzB,KAAK,CAAC,KAAK,EAAE,CAAA;AACf,CAAC;AAED,MAAa,KAAK;IACC,GAAG,CAAQ;IAE5B,YAAY,OAAe,EAAE,IAAY;QACvC,IAAI,CAAC,GAAG,GAAG,GAAG,OAAO,IAAI,IAAI,EAAE,CAAA;IACjC,CAAC;IAED,WAAW,CAAC,QAAgB;QAC1B,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IAC/B,CAAC;IAED,WAAW;QACT,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAA;QACtC,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,cAAc;QACZ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAA;QACtC,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACxB,CAAC;CACF;AAzBD,sBAyBC"}

package/dist/__mocks__/node-mac-auth.d.ts

@@ -0,0 +1,8 @@
+export declare function _setAvailable(val: boolean): void;
+export declare function _setShouldReject(val: boolean): void;
+export declare function _reset(): void;
+export declare function canPromptTouchID(): boolean;
+export declare function promptTouchID(_opts: {
+    reason: string;
+}): Promise<void>;
+//# sourceMappingURL=node-mac-auth.d.ts.map

package/dist/__mocks__/node-mac-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-mac-auth.d.ts","sourceRoot":"","sources":["../../src/__mocks__/node-mac-auth.ts"],"names":[],"mappings":"AAIA,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAEhD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAEnD;AAED,wBAAgB,MAAM,IAAI,IAAI,CAG7B;AAED,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}

package/dist/__mocks__/node-mac-auth.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._setAvailable = _setAvailable;
+exports._setShouldReject = _setShouldReject;
+exports._reset = _reset;
+exports.canPromptTouchID = canPromptTouchID;
+exports.promptTouchID = promptTouchID;
+// Manual mock for node-mac-auth — used in tests without Touch ID hardware
+let available = true;
+let shouldReject = false;
+function _setAvailable(val) {
+    available = val;
+}
+function _setShouldReject(val) {
+    shouldReject = val;
+}
+function _reset() {
+    available = true;
+    shouldReject = false;
+}
+function canPromptTouchID() {
+    return available;
+}
+function promptTouchID(_opts) {
+    if (shouldReject)
+        return Promise.reject(new Error('User cancelled'));
+    return Promise.resolve();
+}
+//# sourceMappingURL=node-mac-auth.js.map

package/dist/__mocks__/node-mac-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-mac-auth.js","sourceRoot":"","sources":["../../src/__mocks__/node-mac-auth.ts"],"names":[],"mappings":";;AAIA,sCAEC;AAED,4CAEC;AAED,wBAGC;AAED,4CAEC;AAED,sCAGC;AAxBD,0EAA0E;AAC1E,IAAI,SAAS,GAAG,IAAI,CAAA;AACpB,IAAI,YAAY,GAAG,KAAK,CAAA;AAExB,SAAgB,aAAa,CAAC,GAAY;IACxC,SAAS,GAAG,GAAG,CAAA;AACjB,CAAC;AAED,SAAgB,gBAAgB,CAAC,GAAY;IAC3C,YAAY,GAAG,GAAG,CAAA;AACpB,CAAC;AAED,SAAgB,MAAM;IACpB,SAAS,GAAG,IAAI,CAAA;IAChB,YAAY,GAAG,KAAK,CAAA;AACtB,CAAC;AAED,SAAgB,gBAAgB;IAC9B,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,SAAgB,aAAa,CAAC,KAAyB;IACrD,IAAI,YAAY;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAA;IACpE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;AAC1B,CAAC"}

package/dist/adapter/mcp/http-transport.d.ts

@@ -0,0 +1,34 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface HealthStatus {
+    auth: boolean;
+    db: boolean;
+    lastSync: string | null;
+    uptime: number;
+}
+export interface HttpTransportHandle {
+    close: () => Promise<void>;
+    port: number;
+    host: string;
+    sessionCount: () => number;
+}
+/** Factory result: McpServer + optional callback for client info from MCP initialize handshake */
+export interface McpServerFactoryResult {
+    server: McpServer;
+    onClientInfo?: (info: {
+        name: string;
+        version: string;
+    }) => void;
+}
+/**
+ * Start HTTP transport for daemon mode.
+ *
+ * @param createMcpServerFn Factory that creates a new McpServer per session.
+ *   Can return just an McpServer (backward compat) or { server, onClientInfo }.
+ * @param port Port to bind to (default: 3100)
+ * @param host Host to bind to (default: 127.0.0.1, localhost only for security)
+ * @returns Handle with close() for graceful shutdown
+ */
+export declare function startHttpTransport(createMcpServerFn: () => McpServer | McpServerFactoryResult | Promise<McpServer | McpServerFactoryResult>, port?: number, host?: string, options?: {
+    healthCheck?: () => Promise<HealthStatus> | HealthStatus;
+}): Promise<HttpTransportHandle>;
+//# sourceMappingURL=http-transport.d.ts.map

package/dist/adapter/mcp/http-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-transport.d.ts","sourceRoot":"","sources":["../../../src/adapter/mcp/http-transport.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAKnE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAA;IACb,EAAE,EAAE,OAAO,CAAA;IACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,MAAM,CAAA;CAC3B;AAED,kGAAkG;AAClG,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,SAAS,CAAA;IACjB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACjE;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,iBAAiB,EAAE,MAAM,SAAS,GAAG,sBAAsB,GAAG,OAAO,CAAC,SAAS,GAAG,sBAAsB,CAAC,EACzG,IAAI,GAAE,MAA4B,EAClC,IAAI,GAAE,MAAoB,EAC1B,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAA;CAAE,GACrE,OAAO,CAAC,mBAAmB,CAAC,CAqI9B"}

package/dist/adapter/mcp/http-transport.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startHttpTransport = startHttpTransport;
+/**
+ * Multi-client HTTP transport for daemon mode.
+ *
+ * Uses MCP SDK's StreamableHTTPServerTransport. Each client connection gets
+ * its own transport + McpServer instance — a single transport does NOT
+ * support concurrent clients.
+ *
+ * Security: binds to 127.0.0.1 only (localhost). No authentication on HTTP
+ * endpoint — same trust model as stdio (any local process can connect).
+ */
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const node_http_1 = require("node:http");
+const node_crypto_1 = require("node:crypto");
+const constants_1 = require("../../config/constants");
+/**
+ * Start HTTP transport for daemon mode.
+ *
+ * @param createMcpServerFn Factory that creates a new McpServer per session.
+ *   Can return just an McpServer (backward compat) or { server, onClientInfo }.
+ * @param port Port to bind to (default: 3100)
+ * @param host Host to bind to (default: 127.0.0.1, localhost only for security)
+ * @returns Handle with close() for graceful shutdown
+ */
+async function startHttpTransport(createMcpServerFn, port = constants_1.DEFAULT_DAEMON_PORT, host = '127.0.0.1', options) {
+    const sessions = new Map();
+    const httpServer = (0, node_http_1.createServer)(async (req, res) => {
+        // Health endpoint
+        if (req.method === 'GET' && req.url === '/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            if (options?.healthCheck) {
+                try {
+                    const extra = await options.healthCheck();
+                    const allOk = extra.auth && extra.db;
+                    res.end(JSON.stringify({ status: allOk ? 'ok' : 'degraded', sessions: sessions.size, ...extra }));
+                }
+                catch {
+                    res.end(JSON.stringify({ status: 'degraded', sessions: sessions.size, error: 'health check failed' }));
+                }
+            }
+            else {
+                res.end(JSON.stringify({ status: 'ok', sessions: sessions.size }));
+            }
+            return;
+        }
+        // Only /mcp endpoint for MCP protocol
+        if (req.url !== '/mcp') {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Not found' }));
+            return;
+        }
+        // Extract session ID from header (MCP protocol)
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId && sessions.has(sessionId)) {
+            // Existing session — route to its transport
+            const session = sessions.get(sessionId);
+            await session.transport.handleRequest(req, res);
+        }
+        else {
+            // New session — create transport + server instance
+            let transport;
+            try {
+                transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => (0, node_crypto_1.randomUUID)(),
+                });
+                const factoryResult = await Promise.resolve(createMcpServerFn());
+                // Unwrap factory result: support both plain McpServer and { server, onClientInfo }.
+                // Use duck-typing: a plain McpServer has .connect() directly; McpServerFactoryResult
+                // wraps it in .server. This works with both real instances and jest mock instances.
+                let mcpServer;
+                let onClientInfo;
+                if (typeof factoryResult.connect === 'function') {
+                    mcpServer = factoryResult;
+                }
+                else {
+                    mcpServer = factoryResult.server;
+                    onClientInfo = factoryResult.onClientInfo;
+                }
+                // Track session cleanup
+                const t = transport;
+                t.onclose = () => {
+                    const sid = t.sessionId;
+                    if (sid)
+                        sessions.delete(sid);
+                };
+                // Set up oninitialized BEFORE connect to capture clientInfo from MCP handshake
+                if (onClientInfo) {
+                    mcpServer.server.oninitialized = () => {
+                        const clientVersion = mcpServer.server.getClientVersion();
+                        if (clientVersion) {
+                            onClientInfo({ name: clientVersion.name, version: clientVersion.version });
+                        }
+                    };
+                }
+                // Connect server to transport
+                await mcpServer.connect(transport);
+                // Handle the request (sessionId is set during handleRequest for POST init)
+                await transport.handleRequest(req, res);
+                // Store session after handleRequest (sessionId becomes available)
+                if (transport.sessionId) {
+                    sessions.set(transport.sessionId, { transport, server: mcpServer });
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[ERROR] Failed to create MCP session: ${message}\n`);
+                // Clean up transport if it was created before the error
+                if (transport) {
+                    try {
+                        transport.close?.();
+                    }
+                    catch { /* best-effort cleanup */ }
+                }
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Failed to create session' }));
+                }
+            }
+        }
+    });
+    // Port conflict detection with clear error message
+    await new Promise((resolve, reject) => {
+        httpServer.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                reject(new Error(`Port ${port} is already in use. Is another vess daemon running?`));
+            }
+            else {
+                reject(err);
+            }
+        });
+        httpServer.listen(port, host, resolve);
+    });
+    return {
+        port,
+        host,
+        sessionCount: () => sessions.size,
+        close: () => {
+            // Graceful shutdown: close all sessions first
+            for (const [, session] of sessions) {
+                session.transport.close?.();
+            }
+            sessions.clear();
+            // Force-close all keep-alive connections (Node 18.2+)
+            httpServer.closeAllConnections();
+            return new Promise((resolve, reject) => {
+                httpServer.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        },
+    };
+}
+//# sourceMappingURL=http-transport.js.map

package/dist/adapter/mcp/http-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-transport.js","sourceRoot":"","sources":["../../../src/adapter/mcp/http-transport.ts"],"names":[],"mappings":"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"}

package/dist/adapter/mcp/mcp-adapter.d.ts

@@ -0,0 +1,37 @@
+import { ExecutionEngine } from '../../core/execution-engine';
+import { MCPToolHandler } from './mcp-server.factory';
+export declare class McpAdapter implements MCPToolHandler {
+    private readonly engine;
+    constructor(engine: ExecutionEngine);
+    callTool(args: {
+        tool: string;
+        action: string;
+        parameters?: Record<string, any>;
+        approval?: {
+            token: string;
+            choice: string;
+            vcTTLMinutes?: number;
+        };
+        pendingRequestId?: string;
+    }): Promise<{
+        success: boolean;
+        data?: any;
+        error?: string;
+        approvalRequired?: any;
+        waitingForApproval?: any;
+    }>;
+    issueToolPermission(args: {
+        tool: string;
+        actions: string[];
+    }): Promise<{
+        success: boolean;
+        data?: any;
+        error?: string;
+    }>;
+    listAvailableTools(): Promise<{
+        success: boolean;
+        data?: any;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=mcp-adapter.d.ts.map

package/dist/adapter/mcp/mcp-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapter/mcp/mcp-adapter.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAGrD,qBAAa,UAAW,YAAW,cAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,eAAe;IAE9C,QAAQ,CAAC,IAAI,EAAE;QACnB,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;QAChC,QAAQ,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,YAAY,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;QACnE,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,GAAG,CAAC;QAAC,kBAAkB,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC;IAczG,mBAAmB,CAAC,IAAI,EAAE;QAC9B,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,EAAE,CAAA;KAClB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAKvD,kBAAkB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAGtF"}