helixbox-cli 0.1.123 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.2.0 - 2026-11-08
+
+### Added
+- Live model discovery, mandate, quote, purchase and result tools for Codex.
+- A stdio MCP server for the same tools in Claude Code.
+- Authenticated image/audio delivery into project-local artifact files.
+
+### Changed
+- Workspace access and installed coding agents no longer require a timed HelixBox access purchase.
+- Optional model calls use phone-approved, bounded Solana USDC mandates on the existing backend.
+- No wallet signing key is passed to the coding agent or written into its MCP configuration.
+
+### Notes
+- Mainnet batch settlement remains experimental. Actual device and wallet verification is required before relying on this beta.
+- Existing agent-provider subscriptions and API charges are separate from model-tool purchases.

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Soham Bharambe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,30 +1,40 @@
-# Lunel CLI
+# Helix Box CLI
 
-Node.js CLI that connects a local machine to the Lunel mobile app through the Lunel gateway. It runs from the project directory you want to expose and keeps filesystem, terminal, process, port, git, and AI actions scoped to that working tree.
+Node.js CLI that connects a local machine to the Helix Box mobile app through the Helix Box gateway. It runs from the project directory you want to expose and keeps filesystem, terminal, process, port, git, and AI actions scoped to that working tree.
 
 ## Requirements
 
 - Node.js 18 or newer
 - npm
-- Lunel mobile app for QR/session pairing
+- Helix Box mobile app for QR/session pairing
 
 ## Usage
 
 Run the published package:
 
 ```bash
-npx lunel-cli
+npx helixbox-cli@latest
 ```
 
-The CLI prints a QR code and session details. Scan the QR code with the Lunel app to connect to the current working directory.
+The CLI prints a QR code and session details. Scan the QR code with the Helix Box app to connect to the current working directory.
+
+## Model tools in 0.2.0
+
+Pairing, workspace controls and access to your installed Codex/Claude Code are free. Their own provider subscriptions remain separate.
+
+The CLI gives Codex and Claude Code five tools: live model discovery, approved mandates, bounded quotes, purchase requests and result retrieval. Choose allowed models and approve a USDC budget in the Android app first. Your foreground phone signs calls within those limits; the CLI and coding agent never receive a wallet signing key.
+
+Optional chat, image and speech calls use real x402 payments on Solana Mainnet. A complete result is prepared before its charge settles and is released only after acknowledgement. Keep the original purchase ID if a response is interrupted; do not buy again to retrieve it. Completed image/audio files are saved in `.helixbox-model-results/` inside your project.
+
+This is an experimental mainnet beta. Start with a small budget and verify pairing, model delivery and returning unused escrow on your phone. The phone must remain foregrounded to approve new calls. Older CLI versions do not expose these tools; restart the CLI and pair again after upgrading.
 
 Common options:
 
 ```bash
-npx lunel-cli --help
-npx lunel-cli --new
-npx lunel-cli --debug
-npx lunel-cli --extra-ports 3000,8080
+npx helixbox-cli --help
+npx helixbox-cli --new
+npx helixbox-cli --debug
+npx helixbox-cli --extra-ports 3000,8080
 ```
 
 Options:
@@ -34,39 +44,39 @@ Options:
 | `-h`, `--help` | Show CLI help |
 | `-n`, `--new` | Create a fresh session code instead of reusing the saved one |
 | `-d`, `--debug` | Enable verbose CLI and AI backend logs |
-| `--extra-ports` | Comma-separated local ports to expose through Lunel |
+| `--extra-ports` | Comma-separated local ports to expose through Helix Box |
 
 ## Configuration
 
-By default, the CLI uses the public Lunel services:
+By default, the CLI uses the public Helix Box services:
 
-- Gateway: `https://gateway.lunel.dev`
-- Manager: `https://manager.lunel.dev`
+- Gateway: `https://helixbox-proxy.onrender.com`
+- Manager: `https://helixbox-manager.onrender.com`
 
 Override them with environment variables when developing against local or custom infrastructure:
 
 ```bash
-LUNEL_PROXY_URL=http://localhost:3001 \
-LUNEL_MANAGER_URL=http://localhost:3002 \
-npx lunel-cli
+HELIXBOX_PROXY_URL=http://localhost:3001 \
+HELIXBOX_MANAGER_URL=http://localhost:3002 \
+npx helixbox-cli
 ```
 
 Other useful environment variables:
 
 | Variable | Description |
 | --- | --- |
-| `LUNEL_PROXY_URL` | Gateway/proxy URL |
-| `LUNEL_MANAGER_URL` | Manager URL |
-| `LUNEL_DEBUG` | Set to `1` for debug logging |
-| `LUNEL_DEBUG_AI` | Set to `1` for AI backend debug logging |
+| `HELIXBOX_PROXY_URL` | Gateway/proxy URL |
+| `HELIXBOX_MANAGER_URL` | Manager URL |
+| `HELIXBOX_DEBUG` | Set to `1` for debug logging |
+| `HELIXBOX_DEBUG_AI` | Set to `1` for AI backend debug logging |
 | `NO_COLOR` | Disable colored terminal output |
 | `FORCE_COLOR` | Force colored terminal output |
 
-Session config is saved per project root in the OS-specific Lunel config directory:
+Session config is saved per project root in the OS-specific Helix Box config directory:
 
-- macOS: `~/Library/Application Support/lunel/config.json`
-- Windows: `%APPDATA%\lunel\config.json`
-- Linux: `$XDG_CONFIG_HOME/lunel/config.json` or `~/.config/lunel/config.json`
+- macOS: `~/Library/Application Support/helixbox/config.json`
+- Windows: `%APPDATA%\helixbox\config.json`
+- Linux: `$XDG_CONFIG_HOME/helixbox/config.json` or `~/.config/helixbox/config.json`
 
 ## Development
 
@@ -95,14 +105,14 @@ The package entrypoint is `dist/index.js`, generated from `src/index.ts`. `npm r
 ```text
 src/
   index.ts              CLI entrypoint and local machine bridge
-  ai/                   Codex/OpenCode provider integration
+  ai/                   Codex, OpenCode, Claude Code and Hermes integration
   transport/            Session transport protocol
   libsodium-wrappers.d.ts
 ```
 
 ## Publishing
 
-The package is published as `lunel-cli`. `prepublishOnly` runs the production build before publishing.
+The package is published as `helixbox-cli`. `prepublishOnly` runs the production build before publishing.
 
 ```bash
 npm publish

package/dist/ai/cli.d.ts

@@ -0,0 +1,59 @@
+import type { AIProvider, AiEventEmitter, CodexPromptOptions, FileAttachment, MessageInfo, ModelSelector, ProviderInfo, SessionInfo } from "./interface.js";
+import type { AiBackend } from "./index.js";
+type CliBackend = Extract<AiBackend, "claude" | "hermes">;
+export declare class CliAgentProvider implements AIProvider {
+    private readonly backend;
+    private emitter;
+    private sessions;
+    private shuttingDown;
+    constructor(backend: CliBackend);
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+    subscribe(emitter: AiEventEmitter): () => void;
+    createSession(title?: string): Promise<{
+        session: SessionInfo;
+    }>;
+    listSessions(): Promise<{
+        sessions: unknown;
+    }>;
+    getSession(id: string): Promise<{
+        session: SessionInfo;
+    }>;
+    deleteSession(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    renameSession(id: string, title: string): Promise<{
+        session: SessionInfo;
+    }>;
+    getMessages(sessionId: string): Promise<{
+        messages: MessageInfo[];
+    }>;
+    statuses(): Promise<{
+        statuses: Record<string, unknown>;
+    }>;
+    prompt(sessionId: string, text: string, model?: ModelSelector, _agent?: string, files?: FileAttachment[], _codexOptions?: CodexPromptOptions): Promise<{
+        ack: true;
+    }>;
+    abort(sessionId: string): Promise<Record<string, never>>;
+    agents(): Promise<{
+        agents: unknown;
+    }>;
+    providers(): Promise<ProviderInfo>;
+    setAuth(): Promise<Record<string, never>>;
+    command(): Promise<{
+        result: unknown;
+    }>;
+    revert(): Promise<Record<string, never>>;
+    unrevert(): Promise<Record<string, never>>;
+    share(): Promise<{
+        share: Record<string, never>;
+    }>;
+    permissionReply(): Promise<Record<string, never>>;
+    private argsForPrompt;
+    private cleanOutput;
+    private finishError;
+    private emit;
+    private requireSession;
+    private toSession;
+}
+export {};

package/dist/ai/cli.js

@@ -0,0 +1,193 @@
+import { spawn, spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import { prepareClaudeModelTools } from './model-tools.js';
+const COMMANDS = { claude: "claude", hermes: "hermes" };
+const DEBUG = process.env.HELIXBOX_DEBUG_AI === "1";
+function commandAvailable(command) {
+    const result = spawnSync(command, ["--version"], {
+        stdio: "ignore",
+        shell: process.platform === "win32",
+    });
+    return !result.error;
+}
+function now() { return Date.now(); }
+export class CliAgentProvider {
+    backend;
+    emitter = null;
+    sessions = new Map();
+    shuttingDown = false;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    async init() {
+        if (!commandAvailable(COMMANDS[this.backend])) {
+            throw new Error(`${COMMANDS[this.backend]} CLI is not installed`);
+        }
+    }
+    async destroy() {
+        this.shuttingDown = true;
+        for (const session of this.sessions.values())
+            session.process?.kill();
+        this.sessions.clear();
+        this.emitter = null;
+    }
+    subscribe(emitter) {
+        this.emitter = emitter;
+        this.shuttingDown = false;
+        return () => { this.emitter = null; };
+    }
+    async createSession(title) {
+        const timestamp = now();
+        const session = {
+            id: `${this.backend}-${crypto.randomUUID()}`,
+            title: title?.trim() || `${this.backend === "claude" ? "Claude Code" : "Hermes"} session`,
+            created: timestamp,
+            updated: timestamp,
+            messages: [],
+        };
+        this.sessions.set(session.id, session);
+        return { session: this.toSession(session) };
+    }
+    async listSessions() {
+        return { sessions: [...this.sessions.values()].map((session) => this.toSession(session)) };
+    }
+    async getSession(id) {
+        return { session: this.toSession(this.requireSession(id)) };
+    }
+    async deleteSession(id) {
+        const session = this.requireSession(id);
+        session.process?.kill();
+        return { deleted: this.sessions.delete(id) };
+    }
+    async renameSession(id, title) {
+        const session = this.requireSession(id);
+        session.title = title.trim() || session.title;
+        session.updated = now();
+        return { session: this.toSession(session) };
+    }
+    async getMessages(sessionId) {
+        return { messages: this.requireSession(sessionId).messages };
+    }
+    async statuses() {
+        const statuses = {};
+        for (const session of this.sessions.values()) {
+            statuses[session.id] = { type: session.process ? "busy" : "idle" };
+        }
+        return { statuses };
+    }
+    async prompt(sessionId, text, model, _agent, files = [], _codexOptions) {
+        const session = this.requireSession(sessionId);
+        if (session.process)
+            throw new Error(`Session ${sessionId} is already running`);
+        const userId = crypto.randomUUID();
+        const assistantId = crypto.randomUUID();
+        const created = now();
+        const prompt = files.length > 0
+            ? `${text}\n\nAttached files: ${files.map((file) => file.filename || file.url).join(", ")}`
+            : text;
+        session.messages.push({ id: userId, role: "user", parts: [{ type: "text", text: prompt }], time: { created, updated: created } });
+        this.emit("message.updated", { info: { sessionID: session.id, id: userId, role: "user", time: { created, updated: created } } });
+        this.emit("message.updated", { info: { sessionID: session.id, id: assistantId, role: "assistant", time: { created, updated: created } } });
+        this.emit("session.status", { sessionID: session.id, status: { type: "busy" } });
+        const args = this.argsForPrompt(prompt, model);
+        const modelTools = this.backend === 'claude' ? await prepareClaudeModelTools() : null;
+        if (modelTools)
+            args.push('--mcp-config', modelTools.filename, '--allowedTools', 'mcp__helixbox__*');
+        const child = spawn(COMMANDS[this.backend], args, {
+            cwd: process.cwd(),
+            env: { ...process.env, ...modelTools?.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: process.platform === "win32",
+        });
+        session.process = child;
+        session.updated = now();
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+        child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+        child.on("error", (error) => { void modelTools?.cleanup(); this.finishError(session, assistantId, error.message); });
+        child.on("close", (code) => {
+            void modelTools?.cleanup();
+            session.process = undefined;
+            if (this.shuttingDown)
+                return;
+            const output = this.cleanOutput(stdout || stderr);
+            if (code !== 0 && !output) {
+                this.finishError(session, assistantId, `${this.backend} exited with code ${code ?? "unknown"}`);
+                return;
+            }
+            const message = {
+                id: assistantId,
+                role: "assistant",
+                parts: [{ type: "text", text: output || "(No output)" }],
+                time: { created, updated: now() },
+            };
+            session.messages.push(message);
+            session.updated = now();
+            this.emit("message.part.updated", { sessionID: session.id, messageID: assistantId, part: { id: `${assistantId}-text`, sessionID: session.id, messageID: assistantId, type: "text", text: output || "(No output)" } });
+            this.emit("session.status", { sessionID: session.id, status: { type: "idle" } });
+        });
+        if (DEBUG)
+            console.log(`[ai] started ${this.backend} prompt for ${session.id}`);
+        return { ack: true };
+    }
+    async abort(sessionId) {
+        const session = this.requireSession(sessionId);
+        session.process?.kill();
+        session.process = undefined;
+        this.emit("session.status", { sessionID: session.id, status: { type: "idle" } });
+        return {};
+    }
+    async agents() {
+        return { agents: [{ name: this.backend === "claude" ? "Claude Code" : "Hermes", mode: "default", description: "Installed local CLI agent" }] };
+    }
+    async providers() {
+        return { providers: [{ id: this.backend, name: this.backend === "claude" ? "Claude Code" : "Hermes", models: {} }], default: {} };
+    }
+    async setAuth() {
+        throw new Error(`${COMMANDS[this.backend]} authentication is managed by its local CLI`);
+    }
+    async command() { throw new Error(`${COMMANDS[this.backend]} command execution is not supported by HelixBox`); }
+    async revert() { throw new Error(`${COMMANDS[this.backend]} revert is not supported by HelixBox`); }
+    async unrevert() { throw new Error(`${COMMANDS[this.backend]} unrevert is not supported by HelixBox`); }
+    async share() { throw new Error(`${COMMANDS[this.backend]} sharing is not supported by HelixBox`); }
+    async permissionReply() { throw new Error(`${COMMANDS[this.backend]} permissions are handled by the CLI`); }
+    argsForPrompt(prompt, model) {
+        if (this.backend === "claude") {
+            const args = ["-p", prompt, "--output-format", "json", "--permission-mode", "plan"];
+            if (model?.modelID)
+                args.push("--model", model.modelID);
+            return args;
+        }
+        const args = ["chat", "-q", prompt];
+        if (model?.modelID)
+            args.push("--model", model.modelID);
+        return args;
+    }
+    cleanOutput(output) {
+        const trimmed = output.replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "").trim();
+        if (this.backend !== "claude")
+            return trimmed;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.is_error)
+                throw new Error(String(parsed.result || parsed.subtype || "Claude Code failed"));
+            return typeof parsed.result === "string" ? parsed.result : trimmed;
+        }
+        catch {
+            return trimmed;
+        }
+    }
+    finishError(session, assistantId, error) {
+        session.process = undefined;
+        this.emit("prompt_error", { sessionID: session.id, error });
+        this.emit("session.status", { sessionID: session.id, status: { type: "idle" } });
+        if (DEBUG)
+            console.warn(`[ai] ${this.backend} prompt failed: ${error}`);
+        void assistantId;
+    }
+    emit(type, properties) { this.emitter?.({ type, properties }); }
+    requireSession(id) { const session = this.sessions.get(id); if (!session)
+        throw new Error(`Session ${id} not found`); return session; }
+    toSession(session) { return { id: session.id, title: session.title, time: { created: session.created, updated: session.updated } }; }
+}

package/dist/ai/codex.js

@@ -5,6 +5,7 @@ import * as crypto from "crypto";
 import * as path from "path";
 import { spawn } from "child_process";
 import { createInterface } from "readline";
+import { MODEL_TOOL_DEFINITIONS, modelTools } from './model-tools.js';
 const THREAD_LIST_SOURCE_KINDS = ["cli", "vscode", "appServer", "exec", "unknown"];
 const CODEX_AGENTS = [
     {
@@ -114,6 +115,7 @@ export class CodexProvider {
         const result = await this.call("thread/start", {
             cwd: process.cwd(),
             persistExtendedHistory: true,
+            dynamicTools: MODEL_TOOL_DEFINITIONS.map(tool => ({ type: 'function', ...tool })),
         });
         const threadObject = this.extractThreadObject(result);
         const threadId = this.extractThreadId(threadObject);
@@ -498,6 +500,14 @@ export class CodexProvider {
     }
     handleServerRequest(method, requestId, params) {
         const session = this.resolveSessionFromPayload(params);
+        if (method === 'item/tool/call') {
+            void modelTools.call(String(params.tool), params.arguments ?? {}).then(value => {
+                this.send({ jsonrpc: '2.0', id: requestId, result: { success: true, contentItems: [{ type: 'inputText', text: JSON.stringify(value) }] } });
+            }).catch(error => {
+                this.send({ jsonrpc: '2.0', id: requestId, result: { success: false, contentItems: [{ type: 'inputText', text: error instanceof Error ? error.message : 'Model tool failed' }] } });
+            });
+            return;
+        }
         if (method === "item/tool/requestUserInput") {
             const questionRequestId = String(requestId);
             const callId = this.extractItemId(params) ?? undefined;
@@ -1178,6 +1188,7 @@ export class CodexProvider {
         const params = {
             threadId,
             persistExtendedHistory: true,
+            dynamicTools: MODEL_TOOL_DEFINITIONS.map(tool => ({ type: 'function', ...tool })),
         };
         if (session?.cwd) {
             params.cwd = session.cwd;

package/dist/ai/index.d.ts

@@ -1,5 +1,7 @@
 import type { AiEvent, ModelSelector, FileAttachment, CodexPromptOptions } from "./interface.js";
-export type AiBackend = "opencode" | "codex";
+export type AiBackend = "opencode" | "codex" | "claude" | "hermes";
+export declare const AI_BACKENDS: readonly AiBackend[];
+export declare function isAiBackend(value: unknown): value is AiBackend;
 export declare class AiManager {
     private _providers;
     private _available;

package/dist/ai/index.js

@@ -1,6 +1,10 @@
-// AI manager — runs both OpenCode and Codex simultaneously and routes calls
+// AI manager — runs every installed provider simultaneously and routes calls
 // by the `backend` field in each request. Backends that fail to init are
 // skipped gracefully; the available list is exposed to the app.
+export const AI_BACKENDS = ["opencode", "codex", "claude", "hermes"];
+export function isAiBackend(value) {
+    return typeof value === "string" && AI_BACKENDS.includes(value);
+}
 const DEBUG_MODE = process.env.HELIXBOX_DEBUG === "1" || process.env.HELIXBOX_DEBUG_AI === "1";
 export class AiManager {
     _providers = {};
@@ -9,6 +13,8 @@ export class AiManager {
         await Promise.allSettled([
             this.tryInit("opencode"),
             this.tryInit("codex"),
+            this.tryInit("claude"),
+            this.tryInit("hermes"),
         ]);
         if (this._available.length === 0) {
             console.warn("[ai] No AI backends available. CLI will continue without AI features.");
@@ -26,12 +32,18 @@ export class AiManager {
                 await p.init();
                 this._providers.opencode = p;
             }
-            else {
+            else if (backend === "codex") {
                 const { CodexProvider } = await import("./codex.js");
                 const p = new CodexProvider();
                 await p.init();
                 this._providers.codex = p;
             }
+            else {
+                const { CliAgentProvider } = await import("./cli.js");
+                const p = new CliAgentProvider(backend);
+                await p.init();
+                this._providers[backend] = p;
+            }
             this._available.push(backend);
         }
         catch (err) {

package/dist/ai/model-mcp.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ai/model-mcp.js

@@ -0,0 +1,66 @@
+import { createModelToolClient, MODEL_TOOL_DEFINITIONS } from './model-tools.js';
+const client = createModelToolClient(() => process.env.HELIXBOX_MODEL_PASSWORD ? { managerUrl: process.env.HELIXBOX_MODEL_MANAGER || 'https://helixbox-manager.onrender.com', password: process.env.HELIXBOX_MODEL_PASSWORD } : null);
+let pending = '', active = 0;
+process.stdin.setEncoding('utf8');
+const send = (value) => process.stdout.write(JSON.stringify(value) + '\n');
+async function handle(raw) {
+    let message;
+    try {
+        message = JSON.parse(raw);
+    }
+    catch {
+        send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Invalid JSON' } });
+        return;
+    }
+    if (!message || message.jsonrpc !== '2.0' || message.id === undefined)
+        return;
+    if (++active > 4) {
+        active--;
+        send({ jsonrpc: '2.0', id: message.id, error: { code: -32000, message: 'Model tool is busy' } });
+        return;
+    }
+    try {
+        let result;
+        if (message.method === 'initialize')
+            result = { protocolVersion: ['2025-11-25', '2025-06-18', '2024-11-05'].includes(message.params?.protocolVersion) ? message.params.protocolVersion : '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'helixbox-model-tools', version: '1.0.0' } };
+        else if (message.method === 'ping')
+            result = {};
+        else if (message.method === 'tools/list')
+            result = { tools: MODEL_TOOL_DEFINITIONS };
+        else if (message.method === 'tools/call') {
+            try {
+                result = { content: [{ type: 'text', text: JSON.stringify(await client.call(message.params?.name, message.params?.arguments ?? {})) }] };
+            }
+            catch (error) {
+                result = { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Model tool failed' }] };
+            }
+        }
+        else {
+            send({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Method not found' } });
+            return;
+        }
+        send({ jsonrpc: '2.0', id: message.id, result });
+    }
+    finally {
+        active--;
+    }
+}
+process.stdin.on('data', (chunk) => {
+    pending += chunk;
+    let newline;
+    while ((newline = pending.indexOf('\n')) >= 0) {
+        const line = pending.slice(0, newline);
+        pending = pending.slice(newline + 1);
+        if (Buffer.byteLength(line) > 32768) {
+            process.exitCode = 1;
+            process.stdin.destroy();
+            return;
+        }
+        if (line.trim())
+            void handle(line);
+    }
+    if (Buffer.byteLength(pending) > 32768) {
+        process.exitCode = 1;
+        process.stdin.destroy();
+    }
+});

package/dist/ai/model-tools.d.ts

@@ -0,0 +1,30 @@
+export interface ModelToolConnection {
+    managerUrl: string;
+    password: string;
+}
+export declare function configureModelTools(resolve: () => ModelToolConnection | null): void;
+export declare function modelToolConnection(): ModelToolConnection | null;
+export declare function prepareClaudeModelTools(): Promise<{
+    filename: string;
+    env: {
+        HELIXBOX_MODEL_MANAGER: string;
+        HELIXBOX_MODEL_PASSWORD: string;
+    };
+    cleanup: () => Promise<void>;
+} | null>;
+export declare const MODEL_TOOL_DEFINITIONS: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+}[];
+export declare function createModelToolClient(resolve: () => ModelToolConnection | null, fetcher?: typeof fetch, workspace?: string): {
+    call(name: string, args: unknown): Promise<unknown>;
+};
+export declare const modelTools: {
+    call(name: string, args: unknown): Promise<unknown>;
+};

package/dist/ai/model-tools.js

@@ -0,0 +1,106 @@
+import { mkdir, lstat, realpath, writeFile, readFile, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+let connection = () => null;
+export function configureModelTools(resolve) { connection = resolve; }
+export function modelToolConnection() { return connection(); }
+export async function prepareClaudeModelTools() {
+    const current = connection();
+    if (!current)
+        return null;
+    const filename = `.helixbox-mcp-${randomUUID()}.json`, file = path.join(process.cwd(), filename);
+    // No credential is written to the project; Claude expands these inherited variables at launch.
+    await writeFile(file, JSON.stringify({ mcpServers: { helixbox: { type: 'stdio', command: process.execPath, args: [fileURLToPath(new URL('./model-mcp.js', import.meta.url))],
+                env: { HELIXBOX_MODEL_MANAGER: '${HELIXBOX_MODEL_MANAGER}', HELIXBOX_MODEL_PASSWORD: '${HELIXBOX_MODEL_PASSWORD}' } } } }), { flag: 'wx', mode: 0o600 });
+    return { filename, env: { HELIXBOX_MODEL_MANAGER: current.managerUrl, HELIXBOX_MODEL_PASSWORD: current.password }, cleanup: () => unlink(file).catch(() => { }) };
+}
+const id = (value) => { if (typeof value !== 'string' || !/^[a-f0-9-]{36}$/.test(value))
+    throw new Error('Invalid purchase or mandate ID'); return value; };
+const string = (value, max) => { if (typeof value !== 'string' || !value || Buffer.byteLength(value) > max)
+    throw new Error('Invalid model tool input'); return value; };
+const schema = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const identifier = { type: 'string', pattern: '^[a-f0-9-]{36}$' };
+export const MODEL_TOOL_DEFINITIONS = [
+    { name: 'helixbox_model_catalog', description: 'Discover live chat, image and speech models. Listing is free; use a quote to get a fixed USDC price.', inputSchema: schema({ search: { type: 'string', maxLength: 100 }, kind: { type: 'string', enum: ['chat', 'image', 'voice'] } }) },
+    { name: 'helixbox_model_mandates', description: 'Read this workspace user’s approved model allowlists, remaining budgets and expiry. Only active mandates can buy tools.', inputSchema: schema({}) },
+    { name: 'helixbox_model_quote', description: 'Quote a bounded model call within an active user-approved mandate. Sends only the supplied prompt to the model service. Never include secrets.', inputSchema: schema({ mandateId: identifier, modelId: { type: 'string', maxLength: 256 }, kind: { type: 'string', enum: ['chat', 'image', 'voice'] }, prompt: { type: 'string', maxLength: 8000 }, maxOutputTokens: { type: 'integer', minimum: 1, maximum: 2048 }, voice: { type: 'string', maxLength: 128 } }, ['mandateId', 'modelId', 'kind', 'prompt']) },
+    { name: 'helixbox_model_purchase', description: 'Queue an existing quote for the paired foreground phone to authorize under its mandate. No agent/server wallet key. Do not repurchase an uncertain operation; poll status.', inputSchema: schema({ purchaseId: identifier, mandateId: identifier }, ['purchaseId', 'mandateId']) },
+    { name: 'helixbox_model_status', description: 'Read the original purchase result without another payment. Completed images/audio are saved as real project artifacts. Pending means wait for the phone, not buy again.', inputSchema: schema({ purchaseId: identifier }, ['purchaseId']) },
+];
+async function artifact(job, workspace) {
+    const result = job.result;
+    if (!result?.base64)
+        return job;
+    const suffix = result.kind === 'image' && result.mediaType === 'image/png' ? '.png' : result.kind === 'voice' && result.mediaType === 'audio/mpeg' ? '.mp3' : null;
+    if (!suffix || typeof result.base64 !== 'string' || result.base64.length > 16777216 || !/^[A-Za-z0-9+/]*={0,2}$/.test(result.base64))
+        throw new Error('Invalid model artifact');
+    const root = await realpath(workspace), directory = path.join(root, '.helixbox-model-results');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if ((await lstat(directory)).isSymbolicLink() || await realpath(directory) !== directory)
+        throw new Error('Model artifact directory cannot be a symlink');
+    const file = path.join(directory, id(job.id) + suffix), bytes = Buffer.from(result.base64, 'base64');
+    try {
+        await writeFile(file, bytes, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        if ((await lstat(file)).isSymbolicLink() || createHash('sha256').update(await readFile(file)).digest('hex') !== createHash('sha256').update(bytes).digest('hex'))
+            throw new Error('Existing model artifact differs; refusing to overwrite');
+    }
+    const { base64, ...metadata } = result;
+    return { ...job, result: { ...metadata, artifactPath: file } };
+}
+export function createModelToolClient(resolve, fetcher = fetch, workspace = process.cwd()) {
+    async function request(route, body) {
+        const current = resolve();
+        if (!current)
+            throw new Error('Pair a HelixBox workspace first');
+        const url = new URL(current.managerUrl);
+        if (url.protocol !== 'https:')
+            throw new Error('Model tools require an HTTPS manager');
+        const response = await fetcher(url.origin + '/v2/models' + route, { method: body === undefined ? 'GET' : 'POST', headers: { Authorization: `Bearer ${current.password}`, 'Content-Type': 'application/json' },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(120000) });
+        if (resolve()?.password !== current.password)
+            throw new Error('Workspace pairing changed; discard the old result');
+        const value = await response.json().catch(() => null);
+        if (!response.ok)
+            throw new Error(value?.error || `Model operation failed (${response.status})`);
+        return value;
+    }
+    return { async call(name, args) {
+            if (!args || typeof args !== 'object' || Array.isArray(args))
+                throw new Error('Invalid model tool arguments');
+            const input = args;
+            if (!MODEL_TOOL_DEFINITIONS.some(tool => tool.name === name))
+                throw new Error('Unknown model tool');
+            if (name === 'helixbox_model_catalog') {
+                if (input.kind !== undefined && !['chat', 'image', 'voice'].includes(String(input.kind)))
+                    throw new Error('Invalid model kind');
+                const search = input.search === undefined ? '' : string(input.search, 100).toLowerCase(), catalog = await request('');
+                return { paymentsEnabled: catalog.paymentsEnabled, models: catalog.models.filter((m) => (!input.kind || m.kind === input.kind) && `${m.id} ${m.name}`.toLowerCase().includes(search)).slice(0, 20) };
+            }
+            if (name === 'helixbox_model_mandates')
+                return request('/mandates');
+            if (name === 'helixbox_model_quote') {
+                const mandateId = id(input.mandateId), modelId = string(input.modelId, 256), prompt = string(input.prompt, 8000);
+                const { mandates } = await request('/mandates');
+                const mandate = mandates.find((m) => m.id === mandateId && m.state === 'active' && m.policy.expiresAt > Date.now());
+                if (!mandate?.policy.models.some((m) => m.id === modelId && m.kind === input.kind))
+                    throw new Error('User has not approved this model in an active mandate');
+                const quoted = await request('/quotes', { modelId, kind: input.kind, prompt, consent: true, ...input.maxOutputTokens !== undefined ? { maxOutputTokens: input.maxOutputTokens } : {}, ...input.voice !== undefined ? { voice: input.voice } : {} });
+                if (BigInt(quoted.terms.amount) > BigInt(mandate.policy.perCallAmount))
+                    throw new Error('Quoted price exceeds the user’s per-call cap');
+                return quoted;
+            }
+            const purchaseId = id(input.purchaseId);
+            if (name === 'helixbox_model_purchase')
+                return request(`/purchases/${purchaseId}/request`, { mandateId: id(input.mandateId) });
+            let job = await request(`/purchases/${purchaseId}`);
+            if (job.state === 'paid')
+                job = await request(`/purchases/${purchaseId}/resume`, {});
+            return artifact(job, workspace);
+        } };
+}
+export const modelTools = createModelToolClient(() => connection());

package/dist/index.js

@@ -2,7 +2,8 @@
 import { WebSocket } from "ws";
 import qrcode from "qrcode-terminal";
 import shell from "shelljs";
-import { createAiManager } from "./ai/index.js";
+import { createAiManager, isAiBackend } from "./ai/index.js";
+import { configureModelTools } from './ai/model-tools.js';
 import { V2SessionTransport } from "./transport/v2.js";
 import Ignore from "ignore";
 const ignore = Ignore.default;
@@ -14,8 +15,8 @@ import { randomBytes } from "crypto";
 import { spawn, spawnSync, execSync } from "child_process";
 import { createServer, createConnection } from "net";
 import { createInterface } from "readline";
-const DEFAULT_PROXY_URL = normalizeGatewayUrl(process.env.HELIXBOX_PROXY_URL || "https://gateway.helixbox.xyz");
-const MANAGER_URL = normalizeGatewayUrl(process.env.HELIXBOX_MANAGER_URL || "https://manager.helixbox.xyz");
+const DEFAULT_PROXY_URL = normalizeGatewayUrl(process.env.HELIXBOX_PROXY_URL || "https://helixbox-proxy.onrender.com");
+const MANAGER_URL = normalizeGatewayUrl(process.env.HELIXBOX_MANAGER_URL || "https://helixbox-manager.onrender.com");
 const CLI_ARGS = process.argv.slice(2);
 function hasAnyFlag(args, ...flags) {
     return flags.some((flag) => args.includes(flag));
@@ -30,23 +31,25 @@ import { createRequire } from "module";
 const __require = createRequire(import.meta.url);
 const VERSION = __require("../package.json").version;
 const VERBOSE_AI_LOGS = process.env.HELIXBOX_DEBUG_AI === "1";
-const PTY_RELEASE_BASE_URL = "https://github.com/lunel-dev/lunel/releases/download/v0";
+const PTY_RELEASE_BASE_URL = "https://github.com/devndesigner6/helix-box/releases/download/v0";
 const AI_RUNTIME_INSTALL_CANDIDATES = {
     opencode: ["opencode-ai", "@opencode-ai/cli", "opencode"],
     codex: ["@openai/codex", "codex"],
+    claude: ["@anthropic-ai/claude-code", "claude"],
+    hermes: ["hermes-agent", "hermes"],
 };
 const PTY_RELEASES = {
     "linux:x64": {
         fileName: "helixbox-pty-linux-x8664-0",
-        url: `${PTY_RELEASE_BASE_URL}/lunel-pty-linux-x8664-0`,
+        url: `${PTY_RELEASE_BASE_URL}/helixbox-pty-linux-x8664-0`,
     },
     "darwin:arm64": {
         fileName: "helixbox-pty-macos-arm64-0",
-        url: `${PTY_RELEASE_BASE_URL}/lunel-pty-macos-arm64-0`,
+        url: `${PTY_RELEASE_BASE_URL}/helixbox-pty-macos-arm64-0`,
     },
     "win32:x64": {
         fileName: "helixbox-pty-windows-x8664-1.exe",
-        url: `${PTY_RELEASE_BASE_URL}/lunel-pty-windows-x8664-1.exe`,
+        url: `${PTY_RELEASE_BASE_URL}/helixbox-pty-windows-x8664-1.exe`,
     },
 };
 // Root directory - sandbox all file operations to this
@@ -2702,7 +2705,8 @@ async function processMessage(message) {
             case "ai": {
                 if (!aiManager)
                     throw Object.assign(new Error("AI manager not initialized"), { code: "EUNAVAILABLE" });
-                const backend = (payload.backend === "codex" ? "codex" : "opencode");
+                const requestedBackend = payload.backend;
+                const backend = isAiBackend(requestedBackend) ? requestedBackend : "opencode";
                 switch (action) {
                     case "backends":
                         result = { backends: aiManager.availableBackends() };
@@ -3053,6 +3057,10 @@ function isCommandAvailable(command) {
     }
     return !err;
 }
+function isBackendAvailable(backend) {
+    const command = backend === "opencode" ? "opencode" : backend === "codex" ? "codex" : backend;
+    return isCommandAvailable(command);
+}
 function askYesNo(question, defaultValue = false) {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         return Promise.resolve(false);
@@ -3081,7 +3089,7 @@ function installLatestNpmPackage(pkg) {
 }
 async function ensureAiCliRuntimes() {
     const missingBackends = Object.keys(AI_RUNTIME_INSTALL_CANDIDATES)
-        .filter((backend) => !isCommandAvailable(backend));
+        .filter((backend) => !isBackendAvailable(backend));
     if (missingBackends.length === 0)
         return;
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -3095,7 +3103,7 @@ async function ensureAiCliRuntimes() {
         return;
     }
     for (const backend of missingBackends) {
-        if (isCommandAvailable(backend))
+        if (isBackendAvailable(backend))
             continue;
         const candidates = AI_RUNTIME_INSTALL_CANDIDATES[backend];
         let installed = false;
@@ -3103,7 +3111,7 @@ async function ensureAiCliRuntimes() {
             console.log(`[ai] Installing ${backend} via npm package ${pkg}@latest...`);
             if (!installLatestNpmPackage(pkg))
                 continue;
-            if (isCommandAvailable(backend)) {
+            if (isBackendAvailable(backend)) {
                 installed = true;
                 console.log(`[ai] ${backend} installed successfully.`);
                 break;
@@ -3322,6 +3330,7 @@ async function main() {
         }
         currentSessionCode = sessionCodeToUse;
         currentSessionPassword = sessionPasswordToUse;
+        configureModelTools(() => currentSessionPassword ? { managerUrl: MANAGER_URL, password: currentSessionPassword } : null);
         if (usedSavedSession) {
             const reattach = await claimReattach(sessionPasswordToUse);
             currentPrimaryGateway = reattach.proxyUrl;

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "helixbox-cli",
-  "version": "0.1.123",
+  "version": "0.2.0",
+  "description": "Pair a laptop workspace with HelixBox on Android, with bounded model tools for Codex and Claude Code.",
+  "homepage": "https://helixboxide.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devndesigner6/helix-box-solana.git",
+    "directory": "cli"
+  },
   "author": [
     {
       "name": "Soham Bharambe",
@@ -18,7 +25,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc && npm run prepare-bin",