@indigoai-us/hq-cli 5.109.16 → 5.111.0

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

@@ -0,0 +1,49 @@
+/**
+ * Claude Code headless adapter.
+ *
+ *   claude -p <prompt> --output-format stream-json --verbose --permission-mode <mode>
+ *   (<mode> = bypassPermissions by default — verified headless in HQ on
+ *   2026-09-11: `hq --version` ran without a prompt in 3.9 s; acceptEdits
+ *   when the bot's autoApprove is false; HQ_BOT_CLAUDE_PERMISSION_MODE
+ *   overrides both)
+ *          --append-system-prompt-file <file> --effort <level> [--model m]
+ *          (--session-id <uuid> | --resume <uuid>)
+ *
+ * stdout is NDJSON (see messages-stream.ts): each finished assistant message
+ * is posted as progress while the turn runs; the closing `result` event
+ * carries the final text and session_id.
+ * Verified against Claude Code 2.1.258 on 2026-09-12 (fixtures/claude-stream.ndjson).
+ */
+import type { BotRuntime } from "./types.js";
+export declare const CLAUDE_PERMISSION_MODE_ENV = "HQ_BOT_CLAUDE_PERMISSION_MODE";
+export declare const DEFAULT_CLAUDE_PERMISSION_MODE = "bypassPermissions";
+export declare const GATED_CLAUDE_PERMISSION_MODE = "acceptEdits";
+/** No-prompt mode that works even where bypassPermissions is disabled by policy:
+ *  Claude Code's own classifier approves routine tool calls. */
+export declare const FALLBACK_CLAUDE_PERMISSION_MODE = "auto";
+/** Bots think at medium effort: chat replies stay quick without dropping
+ *  HQ's hooks or context. HQ_BOT_CLAUDE_EFFORT overrides it. */
+export declare const CLAUDE_EFFORT_ENV = "HQ_BOT_CLAUDE_EFFORT";
+export declare const DEFAULT_CLAUDE_EFFORT = "medium";
+export declare function claudeEffort(env?: NodeJS.ProcessEnv): string;
+export declare function claudePermissionMode(env?: NodeJS.ProcessEnv, autoApprove?: boolean, explicit?: string): string;
+/**
+ * True when Claude Code refused to start because bypassPermissions is turned
+ * off for this user (managed/enterprise settings: disableBypassPermissionsMode).
+ * Matched loosely on purpose — the wording has changed across releases.
+ */
+export declare function isClaudeBypassDisabled(text: string): boolean;
+/** True when `name` is an executable file in one of PATH's directories. */
+export declare function onPath(name: string, env: NodeJS.ProcessEnv): boolean;
+/**
+ * The Claude desktop app keeps its own Claude Code under
+ * ~/Library/Application Support/Claude/claude-code/<version>/. A Mac that only
+ * has the desktop app has no `claude` on PATH, yet the HQ app counts it as
+ * installed, so a bot must be able to use it too. Newest verified version wins
+ * (versions compare numerically; unverified or half-downloaded ones are
+ * skipped), matching the HQ desktop app's own lookup.
+ */
+export declare function bundledClaudeBin(homeDir?: string): string | null;
+export declare function resolveClaudeBinary(env: NodeJS.ProcessEnv, homeDir?: string): string;
+export declare function createClaudeRuntime(env?: NodeJS.ProcessEnv): BotRuntime;
+//# sourceMappingURL=claude.d.ts.map

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

@@ -0,0 +1,151 @@
+/**
+ * Claude Code headless adapter.
+ *
+ *   claude -p <prompt> --output-format stream-json --verbose --permission-mode <mode>
+ *   (<mode> = bypassPermissions by default — verified headless in HQ on
+ *   2026-09-11: `hq --version` ran without a prompt in 3.9 s; acceptEdits
+ *   when the bot's autoApprove is false; HQ_BOT_CLAUDE_PERMISSION_MODE
+ *   overrides both)
+ *          --append-system-prompt-file <file> --effort <level> [--model m]
+ *          (--session-id <uuid> | --resume <uuid>)
+ *
+ * stdout is NDJSON (see messages-stream.ts): each finished assistant message
+ * is posted as progress while the turn runs; the closing `result` event
+ * carries the final text and session_id.
+ * Verified against Claude Code 2.1.258 on 2026-09-12 (fixtures/claude-stream.ndjson).
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { messagesStreamEvents, messagesStreamFailure, messagesStreamResult } from "./messages-stream.js";
+export const CLAUDE_PERMISSION_MODE_ENV = "HQ_BOT_CLAUDE_PERMISSION_MODE";
+export const DEFAULT_CLAUDE_PERMISSION_MODE = "bypassPermissions";
+export const GATED_CLAUDE_PERMISSION_MODE = "acceptEdits";
+/** No-prompt mode that works even where bypassPermissions is disabled by policy:
+ *  Claude Code's own classifier approves routine tool calls. */
+export const FALLBACK_CLAUDE_PERMISSION_MODE = "auto";
+/** Bots think at medium effort: chat replies stay quick without dropping
+ *  HQ's hooks or context. HQ_BOT_CLAUDE_EFFORT overrides it. */
+export const CLAUDE_EFFORT_ENV = "HQ_BOT_CLAUDE_EFFORT";
+export const DEFAULT_CLAUDE_EFFORT = "medium";
+export function claudeEffort(env = process.env) {
+    return env[CLAUDE_EFFORT_ENV]?.trim() || DEFAULT_CLAUDE_EFFORT;
+}
+export function claudePermissionMode(env = process.env, autoApprove = true, explicit) {
+    const raw = env[CLAUDE_PERMISSION_MODE_ENV]?.trim();
+    if (raw)
+        return raw;
+    if (explicit?.trim())
+        return explicit.trim();
+    return autoApprove ? DEFAULT_CLAUDE_PERMISSION_MODE : GATED_CLAUDE_PERMISSION_MODE;
+}
+/**
+ * True when Claude Code refused to start because bypassPermissions is turned
+ * off for this user (managed/enterprise settings: disableBypassPermissionsMode).
+ * Matched loosely on purpose — the wording has changed across releases.
+ */
+export function isClaudeBypassDisabled(text) {
+    const t = text.toLowerCase();
+    if (!/bypass ?permissions|disablebypasspermissionsmode|skip.permissions/.test(t))
+        return false;
+    return /disabled|not (allowed|permitted|enabled|available)|policy|managed|forbidden|cannot be used/.test(t);
+}
+/** True when `name` is an executable file in one of PATH's directories. */
+export function onPath(name, env) {
+    for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        try {
+            fs.accessSync(path.join(dir, name), fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    return false;
+}
+/**
+ * The Claude desktop app keeps its own Claude Code under
+ * ~/Library/Application Support/Claude/claude-code/<version>/. A Mac that only
+ * has the desktop app has no `claude` on PATH, yet the HQ app counts it as
+ * installed, so a bot must be able to use it too. Newest verified version wins
+ * (versions compare numerically; unverified or half-downloaded ones are
+ * skipped), matching the HQ desktop app's own lookup.
+ */
+export function bundledClaudeBin(homeDir = os.homedir()) {
+    const managed = path.join(homeDir, "Library", "Application Support", "Claude", "claude-code");
+    let names;
+    try {
+        names = fs.readdirSync(managed);
+    }
+    catch {
+        return null;
+    }
+    const candidates = [];
+    for (const name of names) {
+        if (!/^\d+(\.\d+)*$/.test(name))
+            continue;
+        const dir = path.join(managed, name);
+        const bin = path.join(dir, "claude.app", "Contents", "MacOS", "claude");
+        if (!fs.existsSync(path.join(dir, ".verified")) || !fs.existsSync(bin))
+            continue;
+        candidates.push({ version: name.split(".").map(Number), bin });
+    }
+    candidates.sort((a, b) => {
+        for (let i = 0; i < Math.max(a.version.length, b.version.length); i++) {
+            const d = (a.version[i] ?? 0) - (b.version[i] ?? 0);
+            if (d !== 0)
+                return d;
+        }
+        return 0;
+    });
+    return candidates.at(-1)?.bin ?? null;
+}
+export function resolveClaudeBinary(env, homeDir) {
+    if (onPath("claude", env))
+        return "claude";
+    return bundledClaudeBin(homeDir ?? env.HOME ?? os.homedir()) ?? "claude";
+}
+export function createClaudeRuntime(env = process.env) {
+    return {
+        id: "claude",
+        binary: "claude",
+        resolveBinary: (turnEnv) => resolveClaudeBinary(turnEnv),
+        buildArgs(input, scratch) {
+            const args = [
+                "-p",
+                input.prompt,
+                "--output-format",
+                "stream-json",
+                "--verbose",
+                "--permission-mode",
+                claudePermissionMode(env, input.autoApprove !== false, input.permissionMode),
+                "--append-system-prompt-file",
+                input.systemPromptFile,
+                "--effort",
+                input.effort?.trim() || claudeEffort(env),
+            ];
+            // Keep the HQ tree writable even if a caller runs the turn elsewhere.
+            if (input.hqRoot && input.hqRoot !== input.cwd)
+                args.push("--add-dir", input.hqRoot);
+            if (input.model)
+                args.push("--model", input.model);
+            if (input.sessionId)
+                args.push("--resume", input.sessionId);
+            else
+                args.push("--session-id", scratch.newSessionId);
+            return args;
+        },
+        parseOutput(stdout) {
+            return messagesStreamResult(stdout, "claude");
+        },
+        parseStreamLine(line) {
+            return messagesStreamEvents(line);
+        },
+        failureReason(stdout) {
+            return messagesStreamFailure(stdout);
+        },
+    };
+}
+//# sourceMappingURL=claude.js.map

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

@@ -0,0 +1,28 @@
+/**
+ * Codex CLI headless adapter.
+ *
+ *   codex exec --json --skip-git-repo-check -C <cwd> -o <file> [-m m] <prompt>
+ *   codex exec resume --json --skip-git-repo-check -o <file> [-m m] <sid> <prompt>
+ *
+ * stdout is JSONL: {"type":"thread.started","thread_id"}, then
+ * {"type":"item.completed","item":{"type":"agent_message","text"}} …
+ * The final agent message is also written to `-o <file>` (authoritative).
+ * Each `agent_message` item is posted as progress while the turn runs.
+ * The system prompt rides as a preamble in the prompt (codex exec has no
+ * system-prompt flag); it is small and stable across turns.
+ * Verified against Codex CLI on 2026-09-10 (event names; the model itself
+ * cannot run under this machine's account).
+ */
+import { type BotRuntime, type RuntimeStreamEvent, type RuntimeTurnInput } from "./types.js";
+/** Progress events in one codex JSONL line: finished agent messages and tool starts. */
+export declare function codexStreamEvents(line: string): RuntimeStreamEvent[];
+export declare function codexPrompt(input: RuntimeTurnInput): string;
+/**
+ * Pull the real failure out of codex's JSONL. `turn.failed` / `error` events
+ * carry the API error, sometimes as a JSON string
+ * ({"error":{"message":"You've hit your usage limit…"}}); unwrap it. Setup
+ * warnings (`item.completed` with `item.type === "error"`) are not failures.
+ */
+export declare function codexFailureReason(stdout: string): string | undefined;
+export declare function createCodexRuntime(): BotRuntime;
+//# sourceMappingURL=codex.d.ts.map

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

@@ -0,0 +1,147 @@
+/**
+ * Codex CLI headless adapter.
+ *
+ *   codex exec --json --skip-git-repo-check -C <cwd> -o <file> [-m m] <prompt>
+ *   codex exec resume --json --skip-git-repo-check -o <file> [-m m] <sid> <prompt>
+ *
+ * stdout is JSONL: {"type":"thread.started","thread_id"}, then
+ * {"type":"item.completed","item":{"type":"agent_message","text"}} …
+ * The final agent message is also written to `-o <file>` (authoritative).
+ * Each `agent_message` item is posted as progress while the turn runs.
+ * The system prompt rides as a preamble in the prompt (codex exec has no
+ * system-prompt flag); it is small and stable across turns.
+ * Verified against Codex CLI on 2026-09-10 (event names; the model itself
+ * cannot run under this machine's account).
+ */
+import { parseJsonLine, RuntimeError } from "./types.js";
+/** Progress events in one codex JSONL line: finished agent messages and tool starts. */
+export function codexStreamEvents(line) {
+    const ev = parseJsonLine(line);
+    if (!ev || !ev.item || typeof ev.item !== "object")
+        return [];
+    const item = ev.item;
+    if (ev.type === "item.completed" && item.type === "agent_message" && typeof item.text === "string" && item.text.trim()) {
+        return [{ kind: "message", text: item.text.trim() }];
+    }
+    if (ev.type === "item.started" && typeof item.type === "string" && /command|tool|mcp/.test(item.type)) {
+        return [{ kind: "tool", name: item.type }];
+    }
+    return [];
+}
+export function codexPrompt(input) {
+    if (input.sessionId)
+        return input.prompt;
+    return `${input.systemPrompt}\n\n---\n\nMessage from your owner:\n\n${input.prompt}`;
+}
+/**
+ * Pull the real failure out of codex's JSONL. `turn.failed` / `error` events
+ * carry the API error, sometimes as a JSON string
+ * ({"error":{"message":"You've hit your usage limit…"}}); unwrap it. Setup
+ * warnings (`item.completed` with `item.type === "error"`) are not failures.
+ */
+export function codexFailureReason(stdout) {
+    let reason;
+    for (const line of stdout.split("\n")) {
+        const t = line.trim();
+        if (!t.startsWith("{"))
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(t);
+        }
+        catch {
+            continue;
+        }
+        if (ev.type !== "turn.failed" && ev.type !== "error")
+            continue;
+        const err = ev.error && typeof ev.error === "object" ? ev.error : undefined;
+        const raw = typeof err?.message === "string" ? err.message : typeof ev.message === "string" ? ev.message : undefined;
+        if (raw)
+            reason = unwrapApiError(raw);
+    }
+    return reason?.trim() || undefined;
+}
+function unwrapApiError(raw) {
+    const t = raw.trim();
+    if (!t.startsWith("{"))
+        return t;
+    try {
+        const obj = JSON.parse(t);
+        const inner = obj.error && typeof obj.error === "object" ? obj.error : undefined;
+        if (typeof inner?.message === "string")
+            return inner.message;
+        if (typeof obj.message === "string")
+            return obj.message;
+    }
+    catch {
+        /* not JSON */
+    }
+    return t;
+}
+export function createCodexRuntime() {
+    return {
+        id: "codex",
+        binary: "codex",
+        buildArgs(input, scratch) {
+            const common = ["--json", "--skip-git-repo-check", "-o", scratch.outputFile];
+            if (input.autoApprove !== false) {
+                // Headless: nobody can answer an approval prompt, so a gated command
+                // would just fail. The bot runs with the owner's permissions by design.
+                common.push("--dangerously-bypass-approvals-and-sandbox");
+            }
+            else if (input.hqRoot && input.hqRoot !== input.cwd) {
+                common.push("-c", `sandbox_workspace_write.writable_roots=[${JSON.stringify(input.hqRoot)}]`);
+            }
+            if (input.model)
+                common.push("-m", input.model);
+            common.push("-c", `model_reasoning_effort=${JSON.stringify(input.effort?.trim() || "medium")}`);
+            if (input.sessionId) {
+                return ["exec", "resume", ...common, input.sessionId, codexPrompt(input)];
+            }
+            return ["exec", ...common, "-C", input.cwd, codexPrompt(input)];
+        },
+        parseOutput(stdout, extra) {
+            let sessionId;
+            let lastMessage;
+            let errorMessage;
+            for (const line of stdout.split("\n")) {
+                const t = line.trim();
+                if (!t.startsWith("{"))
+                    continue;
+                let ev;
+                try {
+                    ev = JSON.parse(t);
+                }
+                catch {
+                    continue;
+                }
+                if (ev.type === "thread.started" && typeof ev.thread_id === "string")
+                    sessionId = ev.thread_id;
+                if (ev.type === "item.completed" && ev.item && typeof ev.item === "object") {
+                    const item = ev.item;
+                    if (item.type === "agent_message" && typeof item.text === "string")
+                        lastMessage = item.text;
+                    if (item.type === "error" && typeof item.message === "string")
+                        errorMessage = item.message;
+                }
+                if (ev.type === "turn.failed" || ev.type === "error") {
+                    const msg = typeof ev.message === "string" ? ev.message : JSON.stringify(ev).slice(0, 200);
+                    errorMessage = msg;
+                }
+            }
+            const fromFile = extra.outputFileText?.trim();
+            const text = (fromFile || lastMessage || "").trim();
+            if (!text) {
+                throw new RuntimeError(`codex produced no reply${errorMessage ? `: ${errorMessage.slice(0, 200)}` : ""}`, (errorMessage ?? stdout.slice(-400)).slice(0, 400), null);
+            }
+            return { text, sessionId };
+        },
+        parseStreamLine(line) {
+            return codexStreamEvents(line);
+        },
+        failureReason(stdout) {
+            return codexFailureReason(stdout);
+        },
+    };
+}
+//# sourceMappingURL=codex.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * Grok CLI headless adapter.
+ *
+ *   grok -p <prompt> --output-format streaming-messages-json --always-approve
+ *        --no-subagents --cwd <cwd> [-m m] [-r <sessionId>]
+ *
+ * stdout is NDJSON in the Anthropic Messages shape (see messages-stream.ts).
+ * The plain `json` format glued every interim sentence into one reply; the
+ * streaming format lets each message be posted as it is written.
+ * Verified against grok (grok-4.6) on 2026-09-12 (fixtures/grok-stream.ndjson);
+ * the older `{ text, sessionId }` envelope is still accepted.
+ */
+import { type BotRuntime, type RuntimeTurnInput } from "./types.js";
+export declare function grokPrompt(input: RuntimeTurnInput): string;
+export declare function createGrokRuntime(): BotRuntime;
+//# sourceMappingURL=grok.d.ts.map

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

@@ -0,0 +1,67 @@
+/**
+ * Grok CLI headless adapter.
+ *
+ *   grok -p <prompt> --output-format streaming-messages-json --always-approve
+ *        --no-subagents --cwd <cwd> [-m m] [-r <sessionId>]
+ *
+ * stdout is NDJSON in the Anthropic Messages shape (see messages-stream.ts).
+ * The plain `json` format glued every interim sentence into one reply; the
+ * streaming format lets each message be posted as it is written.
+ * Verified against grok (grok-4.6) on 2026-09-12 (fixtures/grok-stream.ndjson);
+ * the older `{ text, sessionId }` envelope is still accepted.
+ */
+import { messagesStreamEvents, messagesStreamFailure, messagesStreamResult } from "./messages-stream.js";
+import { parseJsonLine, RuntimeError } from "./types.js";
+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() {
+    return {
+        id: "grok",
+        binary: "grok",
+        buildArgs(input) {
+            const args = [
+                "-p",
+                grokPrompt(input),
+                "--output-format",
+                "streaming-messages-json",
+                "--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;
+        },
+        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,35 @@
+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;
+}
+/**
+ * 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