helixbox-stellar-cli 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,17 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0 - 2026-11-08
4
+
5
+ ### Added
6
+ - Live model discovery, mandate, quote, purchase and result tools for Codex.
7
+ - A stdio MCP server for the same tools in Claude Code.
8
+ - Authenticated image/audio delivery into project-local artifact files.
9
+
10
+ ### Changed
11
+ - Workspace access and installed coding agents no longer require a timed HelixBox access purchase.
12
+ - Optional model calls use phone-approved, bounded Solana USDC mandates on the existing backend.
13
+ - No wallet signing key is passed to the coding agent or written into its MCP configuration.
14
+
15
+ ### Notes
16
+ - Mainnet batch settlement remains experimental. Actual device and wallet verification is required before relying on this beta.
17
+ - Existing agent-provider subscriptions and API charges are separate from model-tool purchases.
package/LICENSE ADDED
@@ -0,0 +1,7 @@
1
+ Copyright 2026 Soham Bharambe
2
+
3
+ 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:
4
+
5
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6
+
7
+ 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 CHANGED
@@ -1,3 +1,118 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # HelixBox Stellar CLI
2
+
3
+ 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.
4
+
5
+ ## Requirements
6
+
7
+ - Node.js 18 or newer
8
+ - npm
9
+ - Helix Box mobile app for QR/session pairing
10
+
11
+ ## Usage
12
+
13
+ Run the Stellar CLI in your project directory:
14
+
15
+ ```bash
16
+ npx helixbox-stellar-cli
17
+ ```
18
+
19
+ To build and run it from a local checkout:
20
+
21
+ ```bash
22
+ npm ci --ignore-scripts
23
+ npm run build
24
+ node dist/index.js
25
+ ```
26
+
27
+ 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.
28
+
29
+ ## Model tools
30
+
31
+ Pairing, workspace controls and access to your installed Codex/Claude Code are free. Their own provider subscriptions remain separate.
32
+
33
+ The live model catalog is available when the Stellar manager is configured. Stellar x402 payments, model purchases, and recovery are not available yet. The CLI does not receive a wallet signing key.
34
+
35
+ Common options:
36
+
37
+ ```bash
38
+ node dist/index.js --help
39
+ node dist/index.js --new
40
+ node dist/index.js --debug
41
+ node dist/index.js --extra-ports 3000,8080
42
+ ```
43
+
44
+ Options:
45
+
46
+ | Option | Description |
47
+ | --- | --- |
48
+ | `-h`, `--help` | Show CLI help |
49
+ | `-n`, `--new` | Create a fresh session code instead of reusing the saved one |
50
+ | `-d`, `--debug` | Enable verbose CLI and AI backend logs |
51
+ | `--extra-ports` | Comma-separated local ports to expose through Helix Box |
52
+
53
+ ## Configuration
54
+
55
+ The CLI defaults to the separate Stellar manager and proxy used by the mobile app. To use local or other infrastructure, override both URLs:
56
+
57
+ ```bash
58
+ HELIXBOX_PROXY_URL=http://localhost:3001 \
59
+ HELIXBOX_MANAGER_URL=http://localhost:3002 \
60
+ node dist/index.js
61
+ ```
62
+
63
+ Other useful environment variables:
64
+
65
+ | Variable | Description |
66
+ | --- | --- |
67
+ | `HELIXBOX_PROXY_URL` | Gateway/proxy URL |
68
+ | `HELIXBOX_MANAGER_URL` | Manager URL |
69
+ | `HELIXBOX_DEBUG` | Set to `1` for debug logging |
70
+ | `HELIXBOX_DEBUG_AI` | Set to `1` for AI backend debug logging |
71
+ | `NO_COLOR` | Disable colored terminal output |
72
+ | `FORCE_COLOR` | Force colored terminal output |
73
+
74
+ Session config is saved per project root in the OS-specific Helix Box config directory:
75
+
76
+ - macOS: `~/Library/Application Support/helixbox-stellar/config.json`
77
+ - Windows: `%APPDATA%\helixbox-stellar\config.json`
78
+ - Linux: `$XDG_CONFIG_HOME/helixbox-stellar/config.json` or `~/.config/helixbox-stellar/config.json`
79
+
80
+ ## Development
81
+
82
+ Install dependencies:
83
+
84
+ ```bash
85
+ npm install
86
+ ```
87
+
88
+ Build the CLI:
89
+
90
+ ```bash
91
+ npm run build
92
+ ```
93
+
94
+ Run from source output:
95
+
96
+ ```bash
97
+ npm run dev
98
+ ```
99
+
100
+ The package entrypoint is `dist/index.js`, generated from `src/index.ts`. `npm run build` compiles TypeScript and marks the generated entrypoint executable.
101
+
102
+ ## Project Layout
103
+
104
+ ```text
105
+ src/
106
+ index.ts CLI entrypoint and local machine bridge
107
+ ai/ Codex, OpenCode, Claude Code and Hermes integration
108
+ transport/ Session transport protocol
109
+ libsodium-wrappers.d.ts
110
+ ```
111
+
112
+ ## Publishing
113
+
114
+ The package is named `helixbox-stellar-cli`. `prepublishOnly` runs the production build before publishing.
115
+
116
+ ```bash
117
+ npm publish
118
+ ```
@@ -0,0 +1,59 @@
1
+ import type { AIProvider, AiEventEmitter, CodexPromptOptions, FileAttachment, MessageInfo, ModelSelector, ProviderInfo, SessionInfo } from "./interface.js";
2
+ import type { AiBackend } from "./index.js";
3
+ type CliBackend = Extract<AiBackend, "claude" | "hermes">;
4
+ export declare class CliAgentProvider implements AIProvider {
5
+ private readonly backend;
6
+ private emitter;
7
+ private sessions;
8
+ private shuttingDown;
9
+ constructor(backend: CliBackend);
10
+ init(): Promise<void>;
11
+ destroy(): Promise<void>;
12
+ subscribe(emitter: AiEventEmitter): () => void;
13
+ createSession(title?: string): Promise<{
14
+ session: SessionInfo;
15
+ }>;
16
+ listSessions(): Promise<{
17
+ sessions: unknown;
18
+ }>;
19
+ getSession(id: string): Promise<{
20
+ session: SessionInfo;
21
+ }>;
22
+ deleteSession(id: string): Promise<{
23
+ deleted: boolean;
24
+ }>;
25
+ renameSession(id: string, title: string): Promise<{
26
+ session: SessionInfo;
27
+ }>;
28
+ getMessages(sessionId: string): Promise<{
29
+ messages: MessageInfo[];
30
+ }>;
31
+ statuses(): Promise<{
32
+ statuses: Record<string, unknown>;
33
+ }>;
34
+ prompt(sessionId: string, text: string, model?: ModelSelector, _agent?: string, files?: FileAttachment[], _codexOptions?: CodexPromptOptions): Promise<{
35
+ ack: true;
36
+ }>;
37
+ abort(sessionId: string): Promise<Record<string, never>>;
38
+ agents(): Promise<{
39
+ agents: unknown;
40
+ }>;
41
+ providers(): Promise<ProviderInfo>;
42
+ setAuth(): Promise<Record<string, never>>;
43
+ command(): Promise<{
44
+ result: unknown;
45
+ }>;
46
+ revert(): Promise<Record<string, never>>;
47
+ unrevert(): Promise<Record<string, never>>;
48
+ share(): Promise<{
49
+ share: Record<string, never>;
50
+ }>;
51
+ permissionReply(): Promise<Record<string, never>>;
52
+ private argsForPrompt;
53
+ private cleanOutput;
54
+ private finishError;
55
+ private emit;
56
+ private requireSession;
57
+ private toSession;
58
+ }
59
+ export {};
package/dist/ai/cli.js ADDED
@@ -0,0 +1,193 @@
1
+ import { spawn, spawnSync } from "node:child_process";
2
+ import crypto from "node:crypto";
3
+ import { prepareClaudeModelTools } from './model-tools.js';
4
+ const COMMANDS = { claude: "claude", hermes: "hermes" };
5
+ const DEBUG = process.env.HELIXBOX_DEBUG_AI === "1";
6
+ function commandAvailable(command) {
7
+ const result = spawnSync(command, ["--version"], {
8
+ stdio: "ignore",
9
+ shell: process.platform === "win32",
10
+ });
11
+ return !result.error;
12
+ }
13
+ function now() { return Date.now(); }
14
+ export class CliAgentProvider {
15
+ backend;
16
+ emitter = null;
17
+ sessions = new Map();
18
+ shuttingDown = false;
19
+ constructor(backend) {
20
+ this.backend = backend;
21
+ }
22
+ async init() {
23
+ if (!commandAvailable(COMMANDS[this.backend])) {
24
+ throw new Error(`${COMMANDS[this.backend]} CLI is not installed`);
25
+ }
26
+ }
27
+ async destroy() {
28
+ this.shuttingDown = true;
29
+ for (const session of this.sessions.values())
30
+ session.process?.kill();
31
+ this.sessions.clear();
32
+ this.emitter = null;
33
+ }
34
+ subscribe(emitter) {
35
+ this.emitter = emitter;
36
+ this.shuttingDown = false;
37
+ return () => { this.emitter = null; };
38
+ }
39
+ async createSession(title) {
40
+ const timestamp = now();
41
+ const session = {
42
+ id: `${this.backend}-${crypto.randomUUID()}`,
43
+ title: title?.trim() || `${this.backend === "claude" ? "Claude Code" : "Hermes"} session`,
44
+ created: timestamp,
45
+ updated: timestamp,
46
+ messages: [],
47
+ };
48
+ this.sessions.set(session.id, session);
49
+ return { session: this.toSession(session) };
50
+ }
51
+ async listSessions() {
52
+ return { sessions: [...this.sessions.values()].map((session) => this.toSession(session)) };
53
+ }
54
+ async getSession(id) {
55
+ return { session: this.toSession(this.requireSession(id)) };
56
+ }
57
+ async deleteSession(id) {
58
+ const session = this.requireSession(id);
59
+ session.process?.kill();
60
+ return { deleted: this.sessions.delete(id) };
61
+ }
62
+ async renameSession(id, title) {
63
+ const session = this.requireSession(id);
64
+ session.title = title.trim() || session.title;
65
+ session.updated = now();
66
+ return { session: this.toSession(session) };
67
+ }
68
+ async getMessages(sessionId) {
69
+ return { messages: this.requireSession(sessionId).messages };
70
+ }
71
+ async statuses() {
72
+ const statuses = {};
73
+ for (const session of this.sessions.values()) {
74
+ statuses[session.id] = { type: session.process ? "busy" : "idle" };
75
+ }
76
+ return { statuses };
77
+ }
78
+ async prompt(sessionId, text, model, _agent, files = [], _codexOptions) {
79
+ const session = this.requireSession(sessionId);
80
+ if (session.process)
81
+ throw new Error(`Session ${sessionId} is already running`);
82
+ const userId = crypto.randomUUID();
83
+ const assistantId = crypto.randomUUID();
84
+ const created = now();
85
+ const prompt = files.length > 0
86
+ ? `${text}\n\nAttached files: ${files.map((file) => file.filename || file.url).join(", ")}`
87
+ : text;
88
+ session.messages.push({ id: userId, role: "user", parts: [{ type: "text", text: prompt }], time: { created, updated: created } });
89
+ this.emit("message.updated", { info: { sessionID: session.id, id: userId, role: "user", time: { created, updated: created } } });
90
+ this.emit("message.updated", { info: { sessionID: session.id, id: assistantId, role: "assistant", time: { created, updated: created } } });
91
+ this.emit("session.status", { sessionID: session.id, status: { type: "busy" } });
92
+ const args = this.argsForPrompt(prompt, model);
93
+ const modelTools = this.backend === 'claude' ? await prepareClaudeModelTools() : null;
94
+ if (modelTools)
95
+ args.push('--mcp-config', modelTools.filename, '--allowedTools', 'mcp__helixbox__*');
96
+ const child = spawn(COMMANDS[this.backend], args, {
97
+ cwd: process.cwd(),
98
+ env: { ...process.env, ...modelTools?.env, NO_COLOR: "1", FORCE_COLOR: "0" },
99
+ stdio: ["ignore", "pipe", "pipe"],
100
+ shell: process.platform === "win32",
101
+ });
102
+ session.process = child;
103
+ session.updated = now();
104
+ let stdout = "";
105
+ let stderr = "";
106
+ child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
107
+ child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
108
+ child.on("error", (error) => { void modelTools?.cleanup(); this.finishError(session, assistantId, error.message); });
109
+ child.on("close", (code) => {
110
+ void modelTools?.cleanup();
111
+ session.process = undefined;
112
+ if (this.shuttingDown)
113
+ return;
114
+ const output = this.cleanOutput(stdout || stderr);
115
+ if (code !== 0 && !output) {
116
+ this.finishError(session, assistantId, `${this.backend} exited with code ${code ?? "unknown"}`);
117
+ return;
118
+ }
119
+ const message = {
120
+ id: assistantId,
121
+ role: "assistant",
122
+ parts: [{ type: "text", text: output || "(No output)" }],
123
+ time: { created, updated: now() },
124
+ };
125
+ session.messages.push(message);
126
+ session.updated = now();
127
+ 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)" } });
128
+ this.emit("session.status", { sessionID: session.id, status: { type: "idle" } });
129
+ });
130
+ if (DEBUG)
131
+ console.log(`[ai] started ${this.backend} prompt for ${session.id}`);
132
+ return { ack: true };
133
+ }
134
+ async abort(sessionId) {
135
+ const session = this.requireSession(sessionId);
136
+ session.process?.kill();
137
+ session.process = undefined;
138
+ this.emit("session.status", { sessionID: session.id, status: { type: "idle" } });
139
+ return {};
140
+ }
141
+ async agents() {
142
+ return { agents: [{ name: this.backend === "claude" ? "Claude Code" : "Hermes", mode: "default", description: "Installed local CLI agent" }] };
143
+ }
144
+ async providers() {
145
+ return { providers: [{ id: this.backend, name: this.backend === "claude" ? "Claude Code" : "Hermes", models: {} }], default: {} };
146
+ }
147
+ async setAuth() {
148
+ throw new Error(`${COMMANDS[this.backend]} authentication is managed by its local CLI`);
149
+ }
150
+ async command() { throw new Error(`${COMMANDS[this.backend]} command execution is not supported by HelixBox`); }
151
+ async revert() { throw new Error(`${COMMANDS[this.backend]} revert is not supported by HelixBox`); }
152
+ async unrevert() { throw new Error(`${COMMANDS[this.backend]} unrevert is not supported by HelixBox`); }
153
+ async share() { throw new Error(`${COMMANDS[this.backend]} sharing is not supported by HelixBox`); }
154
+ async permissionReply() { throw new Error(`${COMMANDS[this.backend]} permissions are handled by the CLI`); }
155
+ argsForPrompt(prompt, model) {
156
+ if (this.backend === "claude") {
157
+ const args = ["-p", prompt, "--output-format", "json", "--permission-mode", "plan"];
158
+ if (model?.modelID)
159
+ args.push("--model", model.modelID);
160
+ return args;
161
+ }
162
+ const args = ["chat", "-q", prompt];
163
+ if (model?.modelID)
164
+ args.push("--model", model.modelID);
165
+ return args;
166
+ }
167
+ cleanOutput(output) {
168
+ const trimmed = output.replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "").trim();
169
+ if (this.backend !== "claude")
170
+ return trimmed;
171
+ try {
172
+ const parsed = JSON.parse(trimmed);
173
+ if (parsed.is_error)
174
+ throw new Error(String(parsed.result || parsed.subtype || "Claude Code failed"));
175
+ return typeof parsed.result === "string" ? parsed.result : trimmed;
176
+ }
177
+ catch {
178
+ return trimmed;
179
+ }
180
+ }
181
+ finishError(session, assistantId, error) {
182
+ session.process = undefined;
183
+ this.emit("prompt_error", { sessionID: session.id, error });
184
+ this.emit("session.status", { sessionID: session.id, status: { type: "idle" } });
185
+ if (DEBUG)
186
+ console.warn(`[ai] ${this.backend} prompt failed: ${error}`);
187
+ void assistantId;
188
+ }
189
+ emit(type, properties) { this.emitter?.({ type, properties }); }
190
+ requireSession(id) { const session = this.sessions.get(id); if (!session)
191
+ throw new Error(`Session ${id} not found`); return session; }
192
+ toSession(session) { return { id: session.id, title: session.title, time: { created: session.created, updated: session.updated } }; }
193
+ }
@@ -0,0 +1,149 @@
1
+ import type { AIProvider, AiEventEmitter, CodexPromptOptions, FileAttachment, ModelSelector, MessageInfo, ProviderInfo, SessionInfo, ShareInfo } from "./interface.js";
2
+ export declare class CodexProvider implements AIProvider {
3
+ private proc;
4
+ private shuttingDown;
5
+ private emitter;
6
+ private defaultModelContextWindow;
7
+ private nextId;
8
+ private pending;
9
+ private sessions;
10
+ private deletedThreadIds;
11
+ private resumedThreadIds;
12
+ private pendingPermissionRequestIds;
13
+ private pendingQuestionRequestIds;
14
+ private assistantMessageIdByTurnId;
15
+ private partTextById;
16
+ private debugLog;
17
+ private debugHistory;
18
+ init(): Promise<void>;
19
+ destroy(): Promise<void>;
20
+ subscribe(emitter: AiEventEmitter): () => void;
21
+ createSession(title?: string): Promise<{
22
+ session: SessionInfo;
23
+ }>;
24
+ listSessions(): Promise<{
25
+ sessions: unknown;
26
+ }>;
27
+ getSession(id: string): Promise<{
28
+ session: SessionInfo;
29
+ }>;
30
+ deleteSession(id: string): Promise<{
31
+ deleted: boolean;
32
+ }>;
33
+ renameSession(id: string, title: string): Promise<{
34
+ session: SessionInfo;
35
+ }>;
36
+ getMessages(sessionId: string): Promise<{
37
+ messages: MessageInfo[];
38
+ }>;
39
+ prompt(sessionId: string, text: string, model?: ModelSelector, agent?: string, files?: FileAttachment[], codexOptions?: CodexPromptOptions): Promise<{
40
+ ack: true;
41
+ }>;
42
+ abort(sessionId: string): Promise<Record<string, never>>;
43
+ agents(): Promise<{
44
+ agents: unknown;
45
+ }>;
46
+ providers(): Promise<ProviderInfo>;
47
+ setAuth(providerId: string, key: string): Promise<Record<string, never>>;
48
+ command(sessionId: string, command: string, args: string): Promise<{
49
+ result: unknown;
50
+ }>;
51
+ revert(sessionId: string, messageId: string): Promise<Record<string, never>>;
52
+ unrevert(sessionId: string): Promise<Record<string, never>>;
53
+ share(sessionId: string): Promise<{
54
+ share: ShareInfo;
55
+ }>;
56
+ permissionReply(sessionId: string, permissionId: string, response: "once" | "always" | "reject"): Promise<Record<string, never>>;
57
+ questionReply(sessionId: string, questionId: string, answers: string[][]): Promise<Record<string, never>>;
58
+ questionReject(sessionId: string, questionId: string): Promise<Record<string, never>>;
59
+ private send;
60
+ private call;
61
+ private handleLine;
62
+ private handleServerRequest;
63
+ private handleNotification;
64
+ private isCommandApprovalMethod;
65
+ private emitMirroredUserMessage;
66
+ private handleItemStarted;
67
+ private handleStructuredItemCompleted;
68
+ private emitTextPart;
69
+ private emitStructuredToolPart;
70
+ private finishAssistantTurn;
71
+ private emitMessagePartEvent;
72
+ private ensureAssistantMessage;
73
+ private upsertLocalMessagePart;
74
+ private fetchServerThreads;
75
+ private refreshConfigDefaults;
76
+ private refreshSessionMetadata;
77
+ private fetchServerThreadsByArchiveState;
78
+ private fetchModels;
79
+ private fetchModelById;
80
+ private resolveModelId;
81
+ private buildCollaborationMode;
82
+ private parseThreadListEntry;
83
+ private hasNextCursor;
84
+ private ingestThreadMetadata;
85
+ private reconcileSessionsWithServer;
86
+ private mergeSession;
87
+ private upsertSession;
88
+ private ensureLocalSession;
89
+ private ensureThreadResumed;
90
+ private resolveSessionFromPayload;
91
+ private resolveInFlightTurnId;
92
+ private decodeMessagesFromThreadRead;
93
+ private logThreadReadSummary;
94
+ private decodeStoredToolLikePart;
95
+ private describeStoredToolName;
96
+ private extractStoredToolInput;
97
+ private extractStoredToolOutput;
98
+ private decodeStoredCommandExecutionOutput;
99
+ private decodeUserMessageParts;
100
+ private decodeItemText;
101
+ private makeTurnInputPayload;
102
+ private shouldRetryTurnStartWithImageURLField;
103
+ private inferImageMimeFromDataUrl;
104
+ private decodeReasoningItemText;
105
+ private decodePlanItemText;
106
+ private decodeCommandExecutionItemText;
107
+ private decodeFileLikeItemText;
108
+ private normalizedCommandPhase;
109
+ private shortCommand;
110
+ private flattenTextValue;
111
+ private toSessionInfo;
112
+ private extractThreadObject;
113
+ private extractThreadTitleFromUnknown;
114
+ private extractThreadTitle;
115
+ private extractTurnId;
116
+ private extractItemId;
117
+ private extractTextPayload;
118
+ private extractStructuredUserInputQuestions;
119
+ private extractThreadId;
120
+ private extractThreadCwd;
121
+ private extractCreatedAt;
122
+ private extractUpdatedAt;
123
+ private readTimestamp;
124
+ private firstString;
125
+ private firstStringFromSources;
126
+ private readArray;
127
+ private readRawString;
128
+ private readString;
129
+ private asRecord;
130
+ private normalizedItemType;
131
+ private isUserRole;
132
+ private isAssistantMessageItem;
133
+ private extractIncomingItem;
134
+ private describeToolPart;
135
+ private normalizeStructuredType;
136
+ private isFileChangeStructuredItem;
137
+ private extractStructuredOutput;
138
+ private extractDiffLikePayload;
139
+ private renderFileChangeEntriesBody;
140
+ private renderUnifiedDiffBody;
141
+ private extractCanonicalPatch;
142
+ private normalizeDisplayPath;
143
+ private normalizeDirectoryPath;
144
+ private belongsToCurrentRoot;
145
+ private normalizedFileChangeStatus;
146
+ private extractToolInput;
147
+ private extractCommandExecutionInput;
148
+ private describeCompletedItemOutput;
149
+ }