@indigoai-us/hq-cli 5.345.203 → 5.345.204

package/dist/lib/signals/steps/extract.d.ts

@@ -1,6 +1,6 @@
 import { type StoredPriorSignal } from "../prior-signals.js";
 import { type BotRuntimeId } from "../../bot/config.js";
-import type { SignalsStep, StepContext, StepResult } from "./types.js";
+import type { SignalsStep, SpawnSyncFn, StepContext, StepResult } from "./types.js";
 export declare const EXTRACT_SIGNAL_TYPES: readonly ["action_item", "commitment", "decision", "risk", "question", "key_point", "participant_contribution", "summary"];
 export declare const DEFAULT_WORKLIST_LIMIT = 20;
 export declare const DEFAULT_TURN_TIMEOUT_MS: number;
@@ -13,6 +13,20 @@ export declare const WORKLIST_ITEM_TIMEOUT_MS = 10000;
 export declare function worklistTimeoutMs(limit: number): number;
 export declare const CODEX_PERMISSION_PROFILE = "hq_signals_extract";
 export declare const CANDIDATE_WRAPPER_NAME = "write-candidate.sh";
+/** The sandbox profile the step writes to <turn dir>/.grok/sandbox.toml for a grok turn. */
+export declare const GROK_SANDBOX_PROFILE = "hq_signals_extract";
+export declare const GROK_SANDBOX_FILE: string;
+/** The oldest grok whose `--help` lists every flag in GROK_EXTRACT_FLAGS. */
+export declare const GROK_MIN_VERSION = "1.0.70";
+/** Flags a grok turn needs; one missing from `--help` means the installed grok cannot be locked down. */
+export declare const GROK_EXTRACT_FLAGS: readonly ["--permission-mode", "--tools", "--disallowed-tools", "--allow", "--deny", "--sandbox", "--disable-web-search", "--no-subagents", "--max-turns", "--cwd", "--output-format"];
+/**
+ * grok's built-in read-only shell list (its permissions guide, "Read-Only
+ * Shell Commands"): auto-approved even under dontAsk, so each is denied by
+ * name. A Bash rule without `*` is a prefix match, so `Bash(cat)` also covers
+ * `cat` with any arguments.
+ */
+export declare const GROK_READ_ONLY_COMMANDS: readonly ["ls", "cat", "pwd", "date", "whoami", "hostname", "uptime", "ps", "head", "tail", "wc", "sort", "uniq", "tr", "cut", "mkdir", "touch", "git", "grep", "rg", "kubectl"];
 /** The only tools a claude turn may use: Read inside the channel folder and the pinned wrapper. */
 export declare function claudeAllowedTools(channelDir: string, wrapperPath: string): string[];
 export interface PriorSignal {
@@ -36,10 +50,13 @@ export interface ExtractStepOptions {
     resolveBotRuntime?: () => BotRuntimeId | null;
     claudeBin?: string;
     codexBin?: string;
+    grokBin?: string;
     worklistLimit?: number;
     turnTimeoutMs?: number;
     /** Run channels whose source.yaml says run: cloud too (passes --force). */
     force?: boolean;
+    /** OS used to decide whether grok's child-process network block exists. Default: this process. */
+    platform?: NodeJS.Platform;
 }
 interface SourceChannel {
     channel: string;
@@ -77,8 +94,11 @@ export declare function buildExtractPrompt(input: {
     item: WorkItem;
     itemPath: string;
     wrapperPath: string;
-    /** codex has no Read tool; it reads with shell commands inside its sandbox. */
-    runtime?: "claude" | "codex";
+    /**
+     * codex has no Read tool; it reads with shell commands inside its sandbox.
+     * grok reads with read_file and returns candidate commands as JSON data.
+     */
+    runtime?: "claude" | "codex" | "grok";
 }): string;
 /**
  * The per-item candidate command. It pins --company, --audience and
@@ -91,7 +111,16 @@ export declare function buildCandidateWrapper(input: {
     audience: string;
     sourceRef: string;
 }): string;
-/** Parse a stream-json transcript (or a codex --json event stream). */
+/**
+ * Parse a stream-json transcript (claude), a codex --json event stream, or a
+ * grok streaming-json event stream.
+ *
+ * grok writes `{"type":"text","data":…}` deltas and one terminal
+ * `{"type":"end","stopReason":…,"num_turns":n,"total_cost_usd":x}`; a refused
+ * tool call ends the turn with stopReason "cancelled", and an API failure is
+ * `{"type":"error","message":…}`. Both are mapped to an error result so the
+ * item fails and is retried; only "end_turn" is success.
+ */
 export declare function parseTurnOutput(stdout: string): {
     result: Record<string, unknown> | null;
     turns: number;
@@ -134,9 +163,86 @@ export interface TurnScope {
     wrapperPath: string;
     /** companies/{co}/{signals,ontology}/_candidates, realpath. */
     candidateDirs: string[];
+    /**
+     * Text of the pinned writer, when this turn generated one. A grok turn
+     * compares the file to this immediately before executing it.
+     */
+    wrapperBody?: string;
 }
 /** TOML inline table for the codex permission profile's filesystem entries. */
 export declare function codexFilesystemProfile(scope: TurnScope, codexBin: string, envPath: string | undefined): string;
+/**
+ * The sandbox profile for a grok turn, written to <turn dir>/.grok/sandbox.toml.
+ * grok's `strict` already covers the turn dir (cwd), system paths and ~/.grok;
+ * the grants add bash's install prefix (Homebrew bash loads from it) and the
+ * read-only HQ paths of hqTurnGrants. Candidate folders are not granted:
+ * the host writes them after the turn, outside this sandbox.
+ */
+export declare function grokSandboxProfile(scope: TurnScope, envPath: string | undefined): string;
+/** Grok can read the source; candidate writing belongs to the host. */
+export declare function grokAllowRules(channelDir: string): string[];
+/** Parse literal arguments only. No shell ever interprets model output. */
+export declare function grokCandidateArgv(command: string, wrapperPath: string): string[] | null;
+/**
+ * Validate the whole batch before writing. Only the host executes the pinned
+ * writer. When `expectedWrapper` is set, the file is compared to that text
+ * immediately before each exec. Strict can write the turn directory, so a
+ * writer that no longer matches is not run.
+ */
+export declare function executeGrokCandidates(text: string, wrapperPath: string, spawn: SpawnSyncFn, opts: Parameters<SpawnSyncFn>[2], expectedWrapper?: string): string | undefined;
+/**
+ * Read denies for the grok login. Grok matches a `~` tool path literally and
+ * expands `~` only after that check, so the absolute temp home is not enough.
+ * `realHomes` is every home the original login might live under (the process
+ * HOME we copied from, and os.homedir() when that differs).
+ */
+export declare function grokAuthReadDenies(tempHome: string, realHomes: readonly string[]): string[];
+/** Deny rules of a grok turn: every other tool class, the login file, and the read-only shell list. */
+export declare function grokDenyRules(tempHome: string, realHomes: readonly string[]): string[];
+export declare function grokTurnArgs(prompt: string, scope: TurnScope, maxTurns: number, tempHome: string, realHomes: readonly string[]): string[];
+/** Parent env keys copied into a grok turn. Everything else, including credentials, stays out. */
+export declare const GROK_ENV_ALLOW: readonly ["PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "LC_CTYPE", "USER", "LOGNAME", "SHELL", "SystemRoot", "COMSPEC", "PATHEXT", "WINDIR", "TERM", "TZ", "HQ_ROOT"];
+/** The turn's environment for grok: an allowlist, no sandbox or config overrides, no Claude or Cursor configuration scans. */
+export declare function grokTurnEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export type GrokExtractSupport = {
+    ok: true;
+} | {
+    ok: false;
+    missing: string[];
+};
+/** Whether `grok --help` lists every flag a locked-down turn needs, and streaming-json output. */
+export declare function grokExtractSupportFromHelp(helpText: string): GrokExtractSupport;
+export declare function resetGrokExtractProbeCache(): void;
+/** Probe `grok --help` once per grok binary path (empty or failed output counts as every flag missing). */
+export declare function probeGrokExtractSupport(grokBin: string, readHelp: () => string): GrokExtractSupport;
+export type GrokAvailability = {
+    installed: false;
+} | {
+    installed: true;
+    support: GrokExtractSupport;
+};
+export interface ToolAvailability {
+    installed: boolean;
+    /** The tool's own answer; null when it did not say (then it is not used as a fallback). */
+    signedIn: boolean | null;
+}
+export type ExtractRuntimeChoice = {
+    runtime: BotRuntimeId;
+    fallback?: string;
+} | {
+    error: string;
+};
+/**
+ * Which runtime runs the turns. The main bot's runtime, except that a grok
+ * that is missing or cannot be locked down is never run: the step uses
+ * claude, then codex, when that tool is installed and signed in, and
+ * otherwise fails. The claude and codex checks run only when needed.
+ */
+export declare function chooseExtractRuntime(main: BotRuntimeId, avail: {
+    grok: () => GrokAvailability;
+    claude: () => ToolAvailability;
+    codex: () => ToolAvailability;
+}, platform?: NodeJS.Platform): ExtractRuntimeChoice;
 export declare function claudeTurnArgs(prompt: string, scope: TurnScope, maxTurns: number, budgetUsd: number): string[];
 export declare function codexTurnArgs(prompt: string, scope: TurnScope, codexBin: string, envPath: string | undefined): string[];
 export declare function extractPartialDocument(ctx: StepContext, doc: PartialDocument, prior: readonly PriorSignal[]): Promise<StepResult>;