@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/bot/runtime/grok-acp.js

@@ -0,0 +1,265 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { planBotRuntimeSpawn } from "./windows.js";
+/** A minimal ACP client for Grok's documented stdio runtime. */
+export class GrokAcpClient {
+    options;
+    nextId = 1;
+    pending = new Map();
+    terminals = new Map();
+    sessionId;
+    text = "";
+    finished = false;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        this.request("initialize", {
+            protocolVersion: 1,
+            clientCapabilities: { terminal: true },
+        }, (result) => this.authenticate(result));
+    }
+    receive(line) {
+        let message;
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return;
+            message = parsed;
+        }
+        catch {
+            return;
+        }
+        if (message.method === "session/update") {
+            this.receiveUpdate(message);
+            return;
+        }
+        if (typeof message.method === "string" && (typeof message.id === "number" || typeof message.id === "string")) {
+            void this.receiveRequest(message);
+            return;
+        }
+        if (typeof message.id !== "number" && typeof message.id !== "string")
+            return;
+        const resolve = this.pending.get(message.id);
+        if (!resolve)
+            return;
+        this.pending.delete(message.id);
+        if (message.error && typeof message.error === "object") {
+            const error = message.error;
+            this.fail(typeof error.message === "string" ? error.message : "Grok ACP request failed");
+            return;
+        }
+        const result = message.result && typeof message.result === "object" ? message.result : {};
+        resolve(result);
+    }
+    request(method, params, complete) {
+        if (this.finished)
+            return;
+        const id = this.nextId++;
+        this.pending.set(id, complete);
+        this.options.send({ jsonrpc: "2.0", id, method, params });
+    }
+    notify(method, params = {}) {
+        this.options.send({ jsonrpc: "2.0", method, params });
+    }
+    authenticate(result) {
+        const methods = Array.isArray(result.authMethods) ? result.authMethods : [];
+        const authMethods = new Set(methods.flatMap((method) => method && typeof method === "object" && typeof method.id === "string"
+            ? [String(method.id)]
+            : []));
+        const apiKey = Object.entries(this.options.env).some(([key, value]) => key.toUpperCase() === "XAI_API_KEY" && Boolean(value?.trim()));
+        const methodId = apiKey && authMethods.has("xai.api_key") ? "xai.api_key" : authMethods.has("cached_token") ? "cached_token" : null;
+        if (!methodId) {
+            this.fail("Grok has no cached login; run `grok login` or configure XAI_API_KEY before starting the bot.");
+            return;
+        }
+        this.request("authenticate", { methodId, _meta: { headless: true } }, () => this.openSession());
+    }
+    openSession() {
+        if (this.options.sessionId) {
+            this.request("session/load", { sessionId: this.options.sessionId, cwd: this.options.cwd, mcpServers: [], _meta: { yoloMode: true } }, (result) => this.prompt(result));
+            return;
+        }
+        this.request("session/new", { cwd: this.options.cwd, mcpServers: [], _meta: { yoloMode: true } }, (result) => this.prompt(result));
+    }
+    prompt(result) {
+        if (typeof result.sessionId !== "string" || !result.sessionId) {
+            this.fail("Grok ACP did not return a session ID");
+            return;
+        }
+        this.sessionId = result.sessionId;
+        this.request("session/prompt", { sessionId: this.sessionId, prompt: [{ type: "text", text: this.options.prompt }] }, (response) => this.complete(response));
+    }
+    receiveUpdate(message) {
+        const params = message.params && typeof message.params === "object" ? message.params : {};
+        const update = params.update && typeof params.update === "object" ? params.update : {};
+        const content = update.content && typeof update.content === "object" ? update.content : {};
+        if (update.sessionUpdate !== "agent_message_chunk" || typeof content.text !== "string")
+            return;
+        this.text += content.text;
+        this.options.onText(JSON.stringify({
+            type: "assistant",
+            message: { role: "assistant", content: [{ type: "text", text: content.text }] },
+            parent_tool_use_id: null,
+            session_id: this.sessionId,
+        }));
+    }
+    complete(response) {
+        if (!this.sessionId) {
+            this.fail("Grok ACP completed without a session ID");
+            return;
+        }
+        if (typeof response.stopReason === "string" && response.stopReason.toLowerCase() === "cancelled") {
+            this.fail("Grok ACP cancelled the bot turn");
+            return;
+        }
+        this.finished = true;
+        this.notify("exit");
+        this.options.onComplete(this.sessionId, this.text);
+    }
+    fail(message) {
+        if (this.finished)
+            return;
+        this.finished = true;
+        this.pending.clear();
+        this.options.onFailure(message);
+    }
+    async receiveRequest(message) {
+        const method = message.method;
+        const params = message.params && typeof message.params === "object" ? message.params : {};
+        try {
+            const result = await this.handleClientRequest(method, params);
+            this.options.send({ jsonrpc: "2.0", id: message.id, result });
+        }
+        catch (err) {
+            this.options.send({
+                jsonrpc: "2.0",
+                id: message.id,
+                error: { code: -32000, message: err instanceof Error ? err.message : String(err) },
+            });
+        }
+    }
+    async handleClientRequest(method, params) {
+        const shortMethod = method.startsWith("x.ai/") ? method.slice("x.ai/".length) : method;
+        if (shortMethod === "session/request_permission") {
+            const options = Array.isArray(params.options) ? params.options : [];
+            const allow = options.find((option) => {
+                if (!option || typeof option !== "object")
+                    return false;
+                const candidate = option;
+                return typeof candidate.optionId === "string" && /allow|approve/i.test(String(candidate.kind ?? candidate.name ?? ""));
+            });
+            if (!allow || typeof allow.optionId !== "string")
+                return { outcome: "cancelled" };
+            return { outcome: "selected", optionId: allow.optionId };
+        }
+        if (shortMethod === "terminal/create")
+            return this.createTerminal(params);
+        if (shortMethod === "terminal/output")
+            return this.terminalOutput(params);
+        if (shortMethod === "terminal/wait_for_exit")
+            return this.waitForTerminal(params);
+        if (shortMethod === "terminal/kill")
+            return this.killTerminal(params);
+        if (shortMethod === "terminal/release")
+            return this.releaseTerminal(params);
+        throw new Error(`Unsupported Grok ACP client request: ${method}`);
+    }
+    createTerminal(params) {
+        if (typeof params.command !== "string" || !params.command)
+            throw new Error("Grok ACP terminal request has no command");
+        const args = Array.isArray(params.args) ? params.args.filter((arg) => typeof arg === "string") : [];
+        const env = { ...this.options.env };
+        if (Array.isArray(params.env)) {
+            for (const entry of params.env) {
+                if (!entry || typeof entry !== "object")
+                    continue;
+                const item = entry;
+                const name = item.name;
+                const value = item.value;
+                if (typeof name === "string" && typeof value === "string") {
+                    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name.toUpperCase()) ?? name;
+                    env[key] = value;
+                }
+            }
+        }
+        const commandPlan = planBotRuntimeSpawn(params.command, args, env);
+        const child = spawn(commandPlan.cmd, commandPlan.args, {
+            cwd: typeof params.cwd === "string" ? params.cwd : this.options.cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(commandPlan.shell ? { shell: commandPlan.shell } : {}),
+            ...(commandPlan.windowsVerbatimArguments !== undefined
+                ? { windowsVerbatimArguments: commandPlan.windowsVerbatimArguments }
+                : {}),
+            windowsHide: true,
+        });
+        let resolveExit;
+        const exited = new Promise((resolve) => {
+            resolveExit = resolve;
+        });
+        const handle = { child, output: "", truncated: false, exitCode: null, exited };
+        const append = (chunk) => {
+            const max = 1_000_000;
+            handle.output += chunk.toString();
+            if (Buffer.byteLength(handle.output) > max) {
+                const bytes = Buffer.from(handle.output);
+                handle.output = bytes.subarray(bytes.length - max).toString();
+                handle.truncated = true;
+            }
+        };
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+        child.once("error", (err) => {
+            handle.output += `\n[hq bot] terminal command failed to start: ${err.message}`;
+            handle.exitCode = 1;
+            resolveExit(1);
+        });
+        child.once("close", (code) => {
+            handle.exitCode = code;
+            resolveExit(code);
+        });
+        const terminalId = randomUUID();
+        this.terminals.set(terminalId, handle);
+        return { terminalId };
+    }
+    getTerminal(params) {
+        if (typeof params.terminalId !== "string")
+            throw new Error("Grok ACP terminal request has no terminalId");
+        const terminal = this.terminals.get(params.terminalId);
+        if (!terminal)
+            throw new Error("Grok ACP requested an unknown terminal");
+        return terminal;
+    }
+    terminalOutput(params) {
+        const terminal = this.getTerminal(params);
+        const limit = typeof params.outputByteLimit === "number" && params.outputByteLimit > 0 ? params.outputByteLimit : 65_536;
+        const bytes = Buffer.from(terminal.output);
+        const output = bytes.length > limit ? bytes.subarray(bytes.length - limit).toString() : terminal.output;
+        return {
+            output,
+            exitStatus: terminal.exitCode === null ? null : { exitCode: terminal.exitCode },
+            truncated: terminal.truncated || bytes.length > limit,
+        };
+    }
+    async waitForTerminal(params) {
+        const terminal = this.getTerminal(params);
+        const exitCode = terminal.exitCode ?? (await terminal.exited);
+        return { exitCode };
+    }
+    killTerminal(params) {
+        const terminal = this.getTerminal(params);
+        if (terminal.child.exitCode === null && terminal.child.signalCode === null)
+            terminal.child.kill();
+        return {};
+    }
+    releaseTerminal(params) {
+        const terminal = this.getTerminal(params);
+        if (terminal.child.exitCode === null && terminal.child.signalCode === null) {
+            throw new Error("Grok ACP cannot release a terminal command that is still running");
+        }
+        this.terminals.delete(String(params.terminalId));
+        return {};
+    }
+}
+//# sourceMappingURL=grok-acp.js.map

package/dist/lib/bot/runtime/grok.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Grok CLI headless adapter.
+ *
+ *   grok -p <prompt> --output-format <streaming format> --always-approve
+ *        --no-subagents --cwd <cwd> [-m m] [-r <sessionId>]
+ *
+ * stdout is NDJSON. Older grok (before 0.2.56) wrote Anthropic Messages
+ * shapes under `--output-format streaming-messages-json` (see
+ * messages-stream.ts). grok 0.2.56 dropped that value and emits token
+ * events under `streaming-json`:
+ *
+ *   {"type":"thought","data":…}
+ *   {"type":"text","data":"Hi"}
+ *   {"type":"end","stopReason":"EndTurn","sessionId":…}
+ *
+ * The format is probed from `grok --help` once per process (and cached).
+ * If an older grok still lists `streaming-messages-json`, that is used.
+ * If the probe misses and grok rejects the old value, the turn retries
+ * with `streaming-json`. The older `{ text, sessionId }` envelope is
+ * still accepted.
+ */
+import { type BotRuntime, type RuntimeTurnInput } from "./types.js";
+import type { SpawnPlan } from "../../../utils/windows-spawn.js";
+export declare const GROK_OUTPUT_FORMAT_LEGACY = "streaming-messages-json";
+export declare const GROK_OUTPUT_FORMAT_STREAMING_JSON = "streaming-json";
+export declare function resetGrokOutputFormatCache(): void;
+/** Pick the streaming `--output-format` grok's `--help` says it accepts. */
+export declare function grokOutputFormatFromHelp(helpText: string): string;
+export declare function grokHelpSpawnPlan(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, existsSync?: (candidate: string) => boolean): SpawnPlan;
+/** Probe `grok --help` once and cache the streaming format. */
+export declare function probeGrokOutputFormat(readHelp?: () => string): string;
+/**
+ * When grok 0.2.56 rejects the pre-0.2.56 flag, rewrite argv to
+ * `streaming-json` and remember that for later turns.
+ */
+export declare function grokRetryArgsAfterInvalidOutputFormat(args: string[], stderr: string): string[] | undefined;
+export declare function grokPrompt(input: RuntimeTurnInput): string;
+export declare function createGrokRuntime(opts?: {
+    grokHelp?: string;
+}): BotRuntime;
+//# sourceMappingURL=grok.d.ts.map

package/dist/lib/bot/runtime/grok.js

@@ -0,0 +1,169 @@
+/**
+ * Grok CLI headless adapter.
+ *
+ *   grok -p <prompt> --output-format <streaming format> --always-approve
+ *        --no-subagents --cwd <cwd> [-m m] [-r <sessionId>]
+ *
+ * stdout is NDJSON. Older grok (before 0.2.56) wrote Anthropic Messages
+ * shapes under `--output-format streaming-messages-json` (see
+ * messages-stream.ts). grok 0.2.56 dropped that value and emits token
+ * events under `streaming-json`:
+ *
+ *   {"type":"thought","data":…}
+ *   {"type":"text","data":"Hi"}
+ *   {"type":"end","stopReason":"EndTurn","sessionId":…}
+ *
+ * The format is probed from `grok --help` once per process (and cached).
+ * If an older grok still lists `streaming-messages-json`, that is used.
+ * If the probe misses and grok rejects the old value, the turn retries
+ * with `streaming-json`. The older `{ text, sessionId }` envelope is
+ * still accepted.
+ */
+import { execFileSync } from "node:child_process";
+import { messagesStreamEvents, messagesStreamFailure, messagesStreamResult } from "./messages-stream.js";
+import { parseJsonLine, RuntimeError } from "./types.js";
+import { planBotRuntimeSpawn, resolveRuntimeBinary } from "./windows.js";
+export const GROK_OUTPUT_FORMAT_LEGACY = "streaming-messages-json";
+export const GROK_OUTPUT_FORMAT_STREAMING_JSON = "streaming-json";
+let cachedOutputFormat;
+export function resetGrokOutputFormatCache() {
+    cachedOutputFormat = undefined;
+}
+/** Pick the streaming `--output-format` grok's `--help` says it accepts. */
+export function grokOutputFormatFromHelp(helpText) {
+    const section = /--output-format\s*<OUTPUT_FORMAT>[\s\S]*?\[possible values:\s*([^\]]+)\]/i.exec(helpText);
+    const values = (section?.[1] ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (values.includes(GROK_OUTPUT_FORMAT_LEGACY))
+        return GROK_OUTPUT_FORMAT_LEGACY;
+    if (values.includes(GROK_OUTPUT_FORMAT_STREAMING_JSON))
+        return GROK_OUTPUT_FORMAT_STREAMING_JSON;
+    if (helpText.includes(GROK_OUTPUT_FORMAT_LEGACY))
+        return GROK_OUTPUT_FORMAT_LEGACY;
+    if (/\bstreaming-json\b/.test(helpText))
+        return GROK_OUTPUT_FORMAT_STREAMING_JSON;
+    return GROK_OUTPUT_FORMAT_LEGACY;
+}
+export function grokHelpSpawnPlan(env = process.env, platform = process.platform, existsSync) {
+    const command = resolveRuntimeBinary("grok", env, platform, existsSync);
+    return planBotRuntimeSpawn(command, ["--help"], env, platform);
+}
+function defaultGrokHelp() {
+    const plan = grokHelpSpawnPlan();
+    try {
+        return execFileSync(plan.cmd, plan.args, {
+            encoding: "utf8",
+            timeout: 5_000,
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(plan.shell ? { shell: plan.shell } : {}),
+            ...(plan.windowsVerbatimArguments !== undefined
+                ? { windowsVerbatimArguments: plan.windowsVerbatimArguments }
+                : {}),
+        });
+    }
+    catch (err) {
+        const e = err;
+        return `${e.stdout ?? ""}\n${e.stderr ?? ""}`;
+    }
+}
+/** Probe `grok --help` once and cache the streaming format. */
+export function probeGrokOutputFormat(readHelp = defaultGrokHelp) {
+    if (cachedOutputFormat)
+        return cachedOutputFormat;
+    let help;
+    try {
+        help = readHelp();
+    }
+    catch {
+        help = "";
+    }
+    cachedOutputFormat = grokOutputFormatFromHelp(help);
+    return cachedOutputFormat;
+}
+/**
+ * When grok 0.2.56 rejects the pre-0.2.56 flag, rewrite argv to
+ * `streaming-json` and remember that for later turns.
+ */
+export function grokRetryArgsAfterInvalidOutputFormat(args, stderr) {
+    if (!/invalid value ['"]streaming-messages-json['"]/.test(stderr))
+        return undefined;
+    const i = args.indexOf("--output-format");
+    if (i < 0 || args[i + 1] === GROK_OUTPUT_FORMAT_STREAMING_JSON)
+        return undefined;
+    const next = args.slice();
+    next[i + 1] = GROK_OUTPUT_FORMAT_STREAMING_JSON;
+    cachedOutputFormat = GROK_OUTPUT_FORMAT_STREAMING_JSON;
+    return next;
+}
+export function grokPrompt(input) {
+    if (input.sessionId)
+        return input.prompt;
+    return `${input.systemPrompt}\n\n---\n\nMessage from your owner:\n\n${input.prompt}`;
+}
+export function createGrokRuntime(opts = {}) {
+    const format = opts.grokHelp !== undefined
+        ? grokOutputFormatFromHelp(opts.grokHelp)
+        : (cachedOutputFormat ?? GROK_OUTPUT_FORMAT_LEGACY);
+    return {
+        id: "grok",
+        binary: "grok",
+        resolveBinary: (env, cwd, platform) => resolveRuntimeBinary("grok", env, platform ?? process.platform, undefined, cwd),
+        buildArgs(input) {
+            if (input.platform === "win32") {
+                const args = ["--no-auto-update", "agent", "--always-approve", "--no-subagents"];
+                if (input.model)
+                    args.push("--model", input.model);
+                args.push("--effort", input.effort?.trim() || "medium");
+                args.push("stdio");
+                return args;
+            }
+            const args = [
+                "-p",
+                grokPrompt(input),
+                "--output-format",
+                format,
+                "--always-approve",
+                "--no-subagents",
+                "--cwd",
+                input.cwd,
+            ];
+            if (input.model)
+                args.push("-m", input.model);
+            args.push("--reasoning-effort", input.effort?.trim() || "medium");
+            if (input.sessionId)
+                args.push("-r", input.sessionId);
+            return args;
+        },
+        spawnProtocol(input) {
+            return input.platform === "win32"
+                ? { kind: "grok-acp", prompt: grokPrompt(input), ...(input.sessionId ? { sessionId: input.sessionId } : {}) }
+                : undefined;
+        },
+        parseOutput(stdout) {
+            // Older grok: one `{ text, sessionId }` object.
+            const legacy = stdout
+                .split("\n")
+                .map(parseJsonLine)
+                .find((ev) => ev && typeof ev.text === "string" && ev.type === undefined);
+            if (legacy) {
+                const text = String(legacy.text);
+                if (!text.trim())
+                    throw new RuntimeError("grok produced no reply", stdout.trim().slice(-400), null);
+                return { text, sessionId: typeof legacy.sessionId === "string" ? legacy.sessionId : undefined };
+            }
+            const result = messagesStreamResult(stdout, "grok");
+            if (!result.text.trim())
+                throw new RuntimeError("grok produced no reply", stdout.trim().slice(-400), null);
+            return result;
+        },
+        parseStreamLine(line) {
+            return messagesStreamEvents(line);
+        },
+        failureReason(stdout) {
+            return messagesStreamFailure(stdout);
+        },
+    };
+}
+//# sourceMappingURL=grok.js.map

package/dist/lib/bot/runtime/index.d.ts

@@ -0,0 +1,36 @@
+import type { BotRuntimeId } from "../config.js";
+import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult, type SpawnLike } from "./types.js";
+export * from "./types.js";
+export { createClaudeRuntime, claudePermissionMode } from "./claude.js";
+export { createCodexRuntime, codexPrompt } from "./codex.js";
+export { createGrokRuntime, grokPrompt } from "./grok.js";
+export declare function runtimeFor(id: BotRuntimeId, env?: NodeJS.ProcessEnv): BotRuntime;
+/**
+ * Real child spawn, stdin closed. stdout is delivered line by line while the
+ * process runs (for streaming runtimes) and also returned whole at the end.
+ * No time limit unless `timeoutMs` is set; `signal` kills the process.
+ */
+/**
+ * Every live descendant of `pid` (children first found, deepest last). The
+ * model CLI starts its own tools and shells; stopping only the top process
+ * leaves those running and holding the output pipe open, so a stop would hang
+ * until they finish. POSIX only; empty when `ps` is unavailable.
+ */
+export declare function descendantPids(pid: number, listProcesses?: () => string): number[];
+/** After a stop, wait this long for the output pipes to close before settling anyway. */
+export declare const STOP_SETTLE_GRACE_MS = 2000;
+export declare const defaultSpawn: SpawnLike;
+export interface RunTurnDeps {
+    spawnImpl?: SpawnLike;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    scratchDir?: string;
+    newSessionId?: () => string;
+    platform?: NodeJS.Platform;
+}
+/**
+ * Run one turn: spawn the runtime CLI, parse the reply, clean up scratch.
+ * Throws RuntimeError (with a bounded stderr excerpt) on any failure.
+ */
+export declare function runRuntimeTurn(runtime: BotRuntime, input: RuntimeTurnInput, deps?: RunTurnDeps): Promise<RuntimeTurnResult>;
+//# sourceMappingURL=index.d.ts.map