@indigoai-us/hq-cli 5.345.129 → 5.345.130

package/dist/command-catalog.generated.d.ts

@@ -9124,6 +9124,35 @@ export declare const COMMAND_CATALOG: readonly [{
             }];
             readonly subcommands: readonly [];
         }];
+    }, {
+        readonly name: "workflow";
+        readonly description: "Workflow orchestration";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: true;
+        readonly usage: "[options] [command]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [{
+            readonly name: "run";
+            readonly description: "Run a workflow script or pipeline lane";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly helpOption: false;
+            readonly helpCommand: false;
+            readonly usage: "[args...]";
+            readonly helpText: readonly [];
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+                readonly description: "";
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }];
     }, {
         readonly name: "session-journal";
         readonly description: "Write and read session journal entries";

package/dist/command-catalog.generated.js

@@ -11073,6 +11073,40 @@ export const COMMAND_CATALOG = [
                     }
                 ]
             },
+            {
+                "name": "workflow",
+                "description": "Workflow orchestration",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": true,
+                "usage": "[options] [command]",
+                "helpText": [],
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "run",
+                        "description": "Run a workflow script or pipeline lane",
+                        "aliases": [],
+                        "hidden": false,
+                        "helpOption": false,
+                        "helpCommand": false,
+                        "usage": "[args...]",
+                        "helpText": [],
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true,
+                                "description": ""
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    }
+                ]
+            },
             {
                 "name": "session-journal",
                 "description": "Write and read session journal entries",

package/dist/commands/core-pipeline-workflow-runner-native.d.ts

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/** # hq-core: public */
+/**
+ * workflow-runner.mjs — multi-agent workflow orchestration over headless
+ * coding-agent CLIs (Codex, Grok, Claude), with human gates.
+ *
+ * Runs a plain-JavaScript orchestration script (Workflow-tool authoring shape:
+ * agent()/parallel()/pipeline()/phase()/log()/gate()/workflow(), top-level
+ * await, top-level return) where every agent() call spawns a headless CLI
+ * subprocess chosen by opts.engine:
+ *
+ *   engine "codex" (default) — `codex exec` with the unattended-run flags
+ *     (--dangerously-bypass-hook-trust --skip-git-repo-check
+ *      --dangerously-bypass-approvals-and-sandbox); result read from a
+ *     dedicated --output-last-message file (transcripts are huge — never
+ *     tailed); structured output via --output-schema.
+ *   engine "grok" — `grok --single` / `grok -p` (aliases) with
+ *     --permission-mode bypassPermissions --always-approve --output-format json;
+ *     result unwrapped from the JSON envelope; structured output via
+ *     --json-schema when the CLI supports it (in-prompt fallback otherwise).
+ *   engine "claude" — `claude -p` (single-turn headless) with
+ *     --permission-mode bypassPermissions --output-format json; the result
+ *     envelope ({type,subtype,is_error,result,stop_reason,permission_denials})
+ *     is captured from stdout and unwrapped to its `result` text — a run that
+ *     ended in error (is_error / subtype != success) fails loudly instead of
+ *     surfacing downstream as a bogus parse error; structured output via a
+ *     schema instruction appended to the prompt (the CLI has no schema flag),
+ *     parsed from the reply. Hooks run normally: bypassPermissions skips only
+ *     the interactive prompt, so HQ's PreToolUse/SessionStart hooks still fire.
+ *
+ * Hardening shared by both engines:
+ *   - soft per-agent timeout: on expiry the agent is NOT killed — a
+ *     TIMEOUT WARNING line prints to stdout and repeats every interval so the
+ *     watching orchestrator decides to kill the process group
+ *     (`kill -- -<pid>`) or let it run
+ *   - stdin closed (/dev/null) — headless CLIs otherwise block on stdin
+ *   - every agent is anchored at the HQ root (codex via -C, grok and claude via
+ *     spawn cwd) so project-level agent config and safety hooks load; opts.cd names
+ *     the task's directory and is injected as a prompt preamble, and must
+ *     resolve inside the HQ root (or to a company repo symlink registered
+ *     under repos/ or companies/manifest.yaml)
+ *   - stderr (and codex's combined output) streamed to a per-agent log file
+ *   - CPU governor: at high load, resolved concurrency is halved (floor 1)
+ *
+ * Human gates (spec: core/knowledge/public/hq-core/workflow-gates-spec.md):
+ *   gate(id, question, opts?) pauses the run IN PLACE — a self-contained
+ *   question file lands in <gates>/pending/, a GATE OPEN line prints to
+ *   stdout (even under --quiet — it is the wake signal), and the run polls
+ *   until <gates>/answered/<id>.json exists, then resumes and returns the
+ *   parsed answer. No agents run and no concurrency slot is held while gated.
+ *   Answers are durable: an already-answered id returns instantly
+ *   (GATE CACHED), so a re-launched run never re-asks a human. Answer with
+ *   `bash core/scripts/workflow-gate.sh answer <id> <choice|N>` (the runner
+ *   prints whichever copy exists on this install).
+ *
+ * Usage:
+ *   node core/scripts/workflow-runner.mjs <script.mjs> [options]
+ *   node core/scripts/workflow-runner.mjs --eval '<script source>' [options]
+ *
+ * Options:
+ *   --args <json>        Value exposed to the script as `args`
+ *   --concurrency <n>    Max concurrent agent processes
+ *                        (default: min(16, cores-2), env HQ_WORKFLOW_CONCURRENCY)
+ *   --timeout <secs>     Default per-agent soft timeout — the warning interval
+ *                        (default: 1800, env HQ_WORKFLOW_TIMEOUT_SECS)
+ *   --run-dir <dir>      Where logs/journal land
+ *                        (default: <hq-root>/workspace/tmp/workflow-runner/<runId>)
+ *   --resume <runId|dir> Replay a previous run's finished agents instead of
+ *                        re-running them. Walks the recorded calls in order and
+ *                        returns each cached result until one call differs
+ *                        (edited prompt, changed model, new args); from that
+ *                        point the run is live. Run ids are the directory names
+ *                        under <hq-root>/workspace/tmp/workflow-runner/.
+ *   --quiet              Suppress narrator lines on stderr
+ *   --loop               Persistent lane: no script; wait on
+ *                        <run-dir>/inbox/pending/ and run one phase envelope
+ *                        per agent() call until a {"kind":"stop"} envelope
+ *                        (see "loop mode" below main's helpers; poll interval
+ *                        env HQ_WORKFLOW_LOOP_POLL_MS, default 1000)
+ *   --no-resume          Loop mode: run every phase as a fresh engine call
+ *                        instead of resuming the story's engine session
+ *                        (env HQ_WORKFLOW_NO_RESUME=1 does the same)
+ *
+ * Env:
+ *   HQ_ROOT                    Explicit HQ root. Unset -> auto-detected by
+ *                              walking up from this script (then cwd) to the
+ *                              first dir with companies/manifest.yaml or
+ *                              .claude/settings.json.
+ *   HQ_WORKFLOW_CODEX_BIN      codex binary (default `codex`; tests inject a fake)
+ *   HQ_WORKFLOW_GROK_BIN       grok binary (default `grok`)
+ *   HQ_WORKFLOW_CLAUDE_BIN     claude binary (default `claude`)
+ *   HQ_WORKFLOW_CODEX_PLAN_MODEL / HQ_WORKFLOW_CODEX_EXEC_MODEL
+ *                              codex tier models (defaults gpt-5.6-sol /
+ *                              gpt-5.6-terra)
+ *   HQ_WORKFLOW_GROK_PLAN_MODEL / HQ_WORKFLOW_GROK_EXEC_MODEL
+ *                              grok tier models (default grok-4.6 for both)
+ *   HQ_WORKFLOW_CLAUDE_PLAN_MODEL / HQ_WORKFLOW_CLAUDE_EXEC_MODEL
+ *                              claude tier models (defaults opus / sonnet)
+ *   HQ_WORKFLOW_MODEL          Global model pin overriding every tier map;
+ *                              empty string -> engine CLI default (no -m)
+ *   HQ_WORKFLOW_EFFORT         Default reasoning effort for codex and grok
+ *                              (default high; empty string -> engine CLI default)
+ *   HQ_WORKFLOW_CLAUDE_EFFORT  Default reasoning effort for claude, passed as
+ *                              `--effort` (default low; empty string -> CLI default)
+ *   HQ_WORKFLOW_FAST_MODE      Codex fast mode override (1/0). Per-tier
+ *                              default: exec on, plan off. Ignored by grok.
+ *   HQ_WORKFLOW_REPAIR         Repair passes for an off-contract reply
+ *                              (default 1; 0 disables). When an agent answers
+ *                              in prose instead of the schema's JSON, the
+ *                              engine is asked to restate that same reply as
+ *                              JSON — a reformat, not a re-run of the work.
+ *   HQ_WORKFLOW_CPU_CHECK      High-CPU governor on/off (default on)
+ *   HQ_WORKFLOW_CPU_HIGH_THRESHOLD  Busy fraction counting as high (0.85)
+ *   HQ_WORKFLOW_CPU_BUSY_OVERRIDE   Injected busy fraction (tests)
+ *   HQ_WORKFLOW_GATES_DIR      Gates root (default <hq-root>/workspace/gates;
+ *                              legacy CODEX_WORKFLOW_GATES_DIR honored)
+ *   HQ_WORKFLOW_GATE_POLL_SECS Gate poll interval (default 5; legacy
+ *                              CODEX_WORKFLOW_GATE_POLL_SECS honored)
+ *
+ * Script API (mirrors the Workflow tool):
+ *   agent(prompt, opts) -> Promise<string|object>
+ *     opts.tier (REQUIRED): "plan" (analysis/planning — the flagship model)
+ *           or "exec" (execution — the throughput model). agent() throws if
+ *           missing/invalid so the model choice is never implicit.
+ *     opts.engine: "codex" (default), "grok", or "claude"
+ *     opts: label, phase, schema (ordinary JSON Schema; result parsed+returned
+ *           as an object. Write it the normal way — optional properties simply
+ *           stay out of `required`. On the codex engine it is rewritten into
+ *           the provider's strict dialect on the wire and the answer is mapped
+ *           back, so results are engine-neutral: see
+ *           core/scripts/lib/codex-output-schema.mjs),
+ *           model (explicit override), effort, fastMode (codex only),
+ *           cd (task directory inside the HQ root, or a company repo symlink
+ *           registered under repos/ / companies/manifest.yaml; injected into
+ *           the prompt),
+ *           timeoutSecs (soft), extraArgs (string[])
+ *     A reply that will not parse, or that violates opts.schema, is not the
+ *     end of the call: the engine is asked once to RESTATE its own reply as
+ *     the requested JSON (a reformat — no tools, no re-work, nothing
+ *     invented), because such an agent has almost always finished the work and
+ *     only lost the envelope. HQ_WORKFLOW_REPAIR=0 disables it.
+ *     Every successful call also records its result in the run dir keyed by
+ *     its inputs, which is what --resume replays.
+ *   parallel(thunks)     -> barrier; a thrown thunk resolves to null
+ *   pipeline(items, ...stages) -> no barrier; a throwing stage drops its item
+ *   phase(title) / log(msg)
+ *   gate(id, question, opts?) -> human pause (see above)
+ *   workflow(ref, args?) -> nested script, one level deep
+ *   args / budget (budget is a stub: spend is not tracked for CLI engines)
+ *
+ * The script's top-level return value prints to stdout as JSON.
+ */
+type WorkflowRunnerChild = {
+    pid?: number;
+    unref(): void;
+};
+type WorkflowRunnerSpawnOptions = {
+    detached: true;
+    stdio: 'inherit';
+    env: NodeJS.ProcessEnv;
+    windowsHide?: true;
+};
+type WorkflowRunnerSpawner = (executable: string, argv: string[], options: WorkflowRunnerSpawnOptions) => WorkflowRunnerChild;
+/** Restart this same CLI build with the pinned runner's detached lifecycle. */
+export declare function restartWorkflowRunner(input: {
+    executable: string;
+    argv: string[];
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    spawnProcess: WorkflowRunnerSpawner;
+}): WorkflowRunnerChild;
+/** Execute the native runner behind the hq core command route. */
+export declare function runWorkflowRunnerNative(argv: string[], hqRoot: string): Promise<number>;
+export {};
+//# sourceMappingURL=core-pipeline-workflow-runner-native.d.ts.map