@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/dist/lib/lanes/delivery.js

@@ -0,0 +1,354 @@
+/**
+ * Follow-up delivery decision, per provider and per lane state, in one place.
+ *
+ * Two mechanisms exist. A live provider process drains the drop box on its
+ * next `PreToolUse` event (dropbox.ts). A Claude process is print-and-exit,
+ * so after it exits the only way to deliver is `claude -p --resume <sid>`,
+ * which continues the recorded session and keeps its prompt cache. Codex
+ * (0.155.1) has `codex exec resume <thread-id>`; the id is the `thread_id`
+ * of the `thread.started` event on the `--json` stdout stream, and the same
+ * id comes back on every resumed turn. Grok's CLI (1.0.34) has
+ * `--resume <id>` and its `--single --output-format json` result carries a
+ * `sessionId`, but no live run has shown `--single --resume` continue a
+ * session (the grok account was out of balance when this was written), so
+ * an exited grok lane keeps no delivery path until that is proven.
+ *
+ * Every dispatch site (`hq lanes message`, spawn, reconcile resume) asks this
+ * module rather than testing provider or state inline. A guard bound at one
+ * site and not another is the defect class this branch has already shipped.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+import { parseLaneProvider, } from "./types.js";
+/** Which providers can continue an exited worker from a recorded session id. */
+export const PROVIDER_SESSION_RESUME = {
+    claude: true,
+    codex: true,
+    grok: false,
+};
+export function providerSupportsSessionResume(provider) {
+    return PROVIDER_SESSION_RESUME[parseLaneProvider(provider)];
+}
+/**
+ * States an operator message may resume from, given a session id.
+ *
+ * `done`: the worker finished its brief, wrote a done envelope and exited on
+ * its own. Nothing about the lane says the operator is finished with it; a
+ * follow-up is the normal next step, and the session is intact.
+ *
+ * `blocked`: the worker exited after writing a blocked envelope that names
+ * what it needs. An operator message is usually that missing input. The state
+ * is not terminal (spec §6.7) and nothing stopped the lane deliberately.
+ *
+ * Refused by `hq lanes message`:
+ * `awaiting_input` has its own path, `hq lanes questions answer`, and the
+ * reconcile pass resumes it once every question is answered. `killed` and
+ * `cancelled` were stopped on purpose by the operator; a message must not
+ * silently restart them. `failed` means the run ended without an envelope or
+ * never started; the operator has not seen why. `interrupted` exited with
+ * partial output and no envelope, so the lane's state was never closed
+ * cleanly; only the explicit `hq lanes resume` opt-in continues it
+ * (RESUME_COMMAND_STATES). `queued` and `running` take the drop box, not a
+ * resume.
+ */
+export const RESUMABLE_LANE_STATES = ["done", "blocked"];
+export function isResumableLaneState(state) {
+    return RESUMABLE_LANE_STATES.includes(state);
+}
+/**
+ * States `hq lanes resume` continues from. `interrupted` is the one a plain
+ * message refuses: the run ended without closing its state, and continuing
+ * it is a decision the operator makes by name. `done` and `blocked` are here
+ * so the one command covers every exited-with-a-session case.
+ */
+export const RESUME_COMMAND_STATES = ["interrupted", "done", "blocked"];
+export function isResumeCommandState(state) {
+    return RESUME_COMMAND_STATES.includes(state);
+}
+export const LANE_DELIVERY_MECHANISMS = ["dropbox", "resume", "none"];
+/**
+ * `dropbox`: a process is (or is about to be) alive to drain the inbox.
+ * `resume`: the process has exited, the provider can resume, the state allows
+ * it, and a session id was recorded from the worker's own result.
+ * `none`: nothing can deliver; the caller must refuse and write nothing.
+ */
+export function laneDeliveryMechanism(lane) {
+    if (lane.state === "queued" || lane.state === "running")
+        return "dropbox";
+    if (providerSupportsSessionResume(lane.provider) &&
+        isResumableLaneState(lane.state) &&
+        hasRecordedSessionId(lane)) {
+        return "resume";
+    }
+    return "none";
+}
+export function hasRecordedSessionId(lane) {
+    return (typeof lane.provider_session_id === "string" &&
+        lane.provider_session_id.trim().length > 0);
+}
+export function deliveryRefusalReason(lane) {
+    const state = lane.state;
+    switch (state) {
+        case "queued":
+        case "running":
+            return "";
+        case "awaiting_input":
+            return "Lane is awaiting_input. The worker has exited after writing an ask envelope. Use hq lanes questions answer <question-id>.";
+        case "done":
+        case "blocked": {
+            if (!providerSupportsSessionResume(lane.provider)) {
+                return `Lane is ${state}. Provider ${lane.provider} cannot resume an exited worker; there is no delivery path.`;
+            }
+            if (!hasRecordedSessionId(lane)) {
+                return `Lane is ${state}. No provider session id was recorded from the worker's result, so the session cannot be resumed.`;
+            }
+            return "";
+        }
+        case "killed":
+        case "cancelled":
+            return `Lane is ${state}. The operator stopped it on purpose; a message does not restart it. Resuming from ${state} needs an explicit opt-in, which does not exist yet.`;
+        case "interrupted":
+            return `Lane is ${state}. The run did not close cleanly and the operator has not decided what to do with it. Resuming from ${state} needs an explicit opt-in: hq lanes resume <lane-id> [--text <message>].`;
+        case "failed":
+            return `Lane is ${state}. The run did not close cleanly and the operator has not decided what to do with it. Resuming from ${state} needs an explicit opt-in, which does not exist yet.`;
+        default: {
+            const _exhaustive = state;
+            return _exhaustive;
+        }
+    }
+}
+/** Reasons a resumable provider's exit recorded no session id. Never a fabricated value. */
+export const SESSION_ID_ABSENT_REASONS = [
+    "worker_out_missing",
+    "no_result_json",
+    "no_session_id_field",
+    "no_thread_started_event",
+];
+function nonNegativeInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0
+        ? value
+        : null;
+}
+/**
+ * Parse the `claude -p --output-format json` result. stdout is appended
+ * across runs of the same lane, so the last `type: "result"` object is this
+ * run's. Only `session_id` and the two cache counters are read out; the
+ * prompt, the response body and everything else in the payload stay on disk.
+ */
+export function parseClaudeResultOutput(text) {
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = (lines[i] ?? "").trim();
+        if (!line.startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const rec = parsed;
+        if (rec.type !== "result")
+            continue;
+        const usage = rec.usage && typeof rec.usage === "object" && !Array.isArray(rec.usage)
+            ? rec.usage
+            : {};
+        const sessionId = typeof rec.session_id === "string" && rec.session_id.trim().length > 0
+            ? rec.session_id.trim()
+            : null;
+        return {
+            session_id: sessionId,
+            session_id_absent: sessionId === null ? "no_session_id_field" : null,
+            cache_read_input_tokens: nonNegativeInt(usage.cache_read_input_tokens),
+            cache_creation_input_tokens: nonNegativeInt(usage.cache_creation_input_tokens),
+        };
+    }
+    return {
+        session_id: null,
+        session_id_absent: "no_result_json",
+        cache_read_input_tokens: null,
+        cache_creation_input_tokens: null,
+    };
+}
+/**
+ * Parse the `codex exec --json` event stream. The first event of a run is
+ * `{"type":"thread.started","thread_id":"<uuid>"}`; that id is what
+ * `codex exec resume <id>` takes, and a resumed run emits the same id again.
+ * Usage comes from the last `turn.completed` event: `cached_input_tokens`
+ * is the cache read and `cache_write_input_tokens` the cache creation.
+ * Nothing else on the stream is read out.
+ */
+export function parseCodexEventOutput(text) {
+    let threadId = null;
+    let usage = {};
+    let sawEvent = false;
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (!line.startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const rec = parsed;
+        if (typeof rec.type !== "string")
+            continue;
+        sawEvent = true;
+        if (rec.type === "thread.started" && threadId === null) {
+            threadId =
+                typeof rec.thread_id === "string" && rec.thread_id.trim().length > 0
+                    ? rec.thread_id.trim()
+                    : null;
+        }
+        else if (rec.type === "turn.completed") {
+            usage =
+                rec.usage && typeof rec.usage === "object" && !Array.isArray(rec.usage)
+                    ? rec.usage
+                    : {};
+        }
+    }
+    return {
+        session_id: threadId,
+        session_id_absent: threadId !== null ? null : sawEvent ? "no_thread_started_event" : "no_result_json",
+        cache_read_input_tokens: nonNegativeInt(usage.cached_input_tokens),
+        cache_creation_input_tokens: nonNegativeInt(usage.cache_write_input_tokens),
+    };
+}
+/** Per-provider stdout parser; null for a provider whose exit carries nothing to record. */
+export function parseWorkerRunOutput(provider, text) {
+    switch (parseLaneProvider(provider)) {
+        case "claude":
+            return parseClaudeResultOutput(text);
+        case "codex":
+            return parseCodexEventOutput(text);
+        case "grok":
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Read this run's result from the worker's own stdout. stdout is opened in
+ * append mode across runs, so only bytes past `workerOutOffset` (recorded in
+ * spawn.json at launch) are this run's. Returns null for a provider whose
+ * exit carries nothing to record, so those lanes keep behaving exactly as
+ * before.
+ */
+export function readWorkerRunResult(runDir, provider, 
+/** Bytes of worker.out that belong to earlier runs; parsing starts after them. */
+workerOutOffset = 0) {
+    if (!providerSupportsSessionResume(provider))
+        return null;
+    const outPath = path.join(runDir, "logs", "worker.out");
+    let text;
+    try {
+        const bytes = fs.readFileSync(outPath);
+        text = bytes.subarray(Math.min(workerOutOffset, bytes.length)).toString("utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                session_id: null,
+                session_id_absent: "worker_out_missing",
+                cache_read_input_tokens: null,
+                cache_creation_input_tokens: null,
+            };
+        }
+        process.stderr.write(`hq lanes: failed to read ${outPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        throw err;
+    }
+    return parseWorkerRunOutput(provider, text);
+}
+export const LAUNCH_TRIGGERS = ["admit", "answered_questions", "message", "resume"];
+/**
+ * Refusal for `hq lanes resume`, in precedence order: wrong state, provider
+ * without a resume path, no recorded session. Null when the resume can go.
+ */
+export function resumeCommandRefusal(lane) {
+    if (!isResumeCommandState(lane.state)) {
+        return {
+            error: "lane_not_resumable",
+            message: `Lane is ${lane.state}. hq lanes resume continues a lane in ${RESUME_COMMAND_STATES.join(", ")}; ${lane.state === "awaiting_input"
+                ? "use hq lanes questions answer <question-id>."
+                : lane.state === "queued" || lane.state === "running"
+                    ? "use hq lanes message for a live lane."
+                    : "a lane in this state is not resumed."}`,
+        };
+    }
+    if (!providerSupportsSessionResume(lane.provider)) {
+        return {
+            error: "resume_unsupported",
+            message: `Lane is ${lane.state}. Provider ${lane.provider} cannot resume an exited worker; there is no delivery path.`,
+        };
+    }
+    if (!hasRecordedSessionId(lane)) {
+        return {
+            error: "no_provider_session",
+            message: `Lane is ${lane.state}. No provider session id was recorded from the worker's result, so the session cannot be resumed.`,
+        };
+    }
+    return null;
+}
+/**
+ * Decide fresh-vs-resume for a spawn. Admission always starts fresh with the
+ * brief. Answered questions resume the recorded session when the provider
+ * can, else start fresh with the answers file (today's behaviour). An operator
+ * message can only be a resume, and only when `laneDeliveryMechanism` says so.
+ * `hq lanes resume` is also always a resume, gated by `resumeCommandRefusal`.
+ */
+export function planLaneLaunch(lane, trigger) {
+    switch (trigger.kind) {
+        case "admit":
+            return { mode: "fresh" };
+        case "answered_questions":
+            if (providerSupportsSessionResume(lane.provider) && hasRecordedSessionId(lane)) {
+                return { mode: "resume", session_id: lane.provider_session_id };
+            }
+            return { mode: "fresh" };
+        case "message": {
+            if (laneDeliveryMechanism(lane) !== "resume" || !hasRecordedSessionId(lane)) {
+                throw new LanesError("lane_not_accepting_messages", deliveryRefusalReason(lane) || `Lane is ${lane.state} and cannot be resumed`, { state: lane.state, provider: lane.provider });
+            }
+            return { mode: "resume", session_id: lane.provider_session_id };
+        }
+        case "resume": {
+            const refusal = resumeCommandRefusal(lane);
+            if (refusal !== null || !hasRecordedSessionId(lane)) {
+                throw new LanesError(refusal?.error ?? "no_provider_session", refusal?.message ?? `Lane is ${lane.state} and has no recorded provider session`, { state: lane.state, provider: lane.provider });
+            }
+            return { mode: "resume", session_id: lane.provider_session_id };
+        }
+        default: {
+            const _exhaustive = trigger;
+            return _exhaustive;
+        }
+    }
+}
+/** Lane states a launch may claim `running` from, per trigger. */
+export function claimableStatesFor(trigger) {
+    switch (trigger.kind) {
+        case "admit":
+            return ["queued"];
+        case "answered_questions":
+            return ["awaiting_input"];
+        case "message":
+            return RESUMABLE_LANE_STATES;
+        case "resume":
+            return RESUME_COMMAND_STATES;
+        default: {
+            const _exhaustive = trigger;
+            return _exhaustive;
+        }
+    }
+}
+//# sourceMappingURL=delivery.js.map

package/dist/lib/lanes/dropbox.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Lane drop box: append-only inbox.jsonl plus exactly-once drain (spec §6.5).
+ *
+ * Consume is `rename(inbox.jsonl → draining/<unique>)` — atomic on this box.
+ * Two overlapping drainers cannot both claim the same bytes; a crash after
+ * rename leaves the messages in draining/ for the next drain to recover.
+ * A read-then-truncate is not this mechanism and loses or duplicates under
+ * overlap.
+ */
+import * as fs from "node:fs";
+import { type LaneRecord, type LaneState, type QuestionRecord } from "./types.js";
+export declare const DROPBOX_DIR = "dropbox";
+export declare const INBOX_NAME = "inbox.jsonl";
+export declare const DRAINING_DIR = "draining";
+export declare const DELIVERED_DIR = "delivered";
+export declare const INFLIGHT_DIR = "inflight";
+export interface DropboxMessage {
+    at?: string;
+    message_id?: string;
+    kind?: string;
+    question_id?: string;
+    choice?: string;
+    text: string;
+    [key: string]: unknown;
+}
+export interface DrainDeps {
+    mkdirSync: typeof fs.mkdirSync;
+    renameSync: typeof fs.renameSync;
+    readFileSync: typeof fs.readFileSync;
+    writeFileSync: typeof fs.writeFileSync;
+    unlinkSync: typeof fs.unlinkSync;
+    existsSync: typeof fs.existsSync;
+    readdirSync: typeof fs.readdirSync;
+    rmdirSync: typeof fs.rmdirSync;
+    kill: (pid: number, signal?: NodeJS.Signals | 0) => void;
+    pid: number;
+    unique: () => string;
+    readStarttime?: (pid: number) => number | null;
+    /** Test seam: after observing inbox bytes, before the consume rename. */
+    afterObserveInbox?: () => void;
+    /** Test seam: runs after this process has claimed and read its bytes. */
+    afterRead?: () => void;
+}
+export declare function mintClaimId(): string;
+export declare function assertSafeLaneId(laneId: string): void;
+export declare function dropboxDir(hqRoot: string, laneId: string): string;
+export declare function dropboxInboxPath(hqRoot: string, laneId: string): string;
+/**
+ * Worker tool-call liveness (watcher.ts reads it). A Claude worker run with
+ * `--output-format json` writes nothing to worker.out until it exits, so the
+ * only thing it does observably while working is call tools. Every tool call
+ * runs this drain hook, and the hook records the call here before it touches
+ * the drop box. The file's mtime is the signal; the body is for humans.
+ */
+export declare const TOOL_ACTIVITY_NAME = "tool-activity.json";
+export declare function toolActivityPath(hqRoot: string, laneId: string): string;
+export interface ToolActivityRecord {
+    at: string;
+    hook_pid: number;
+    hook_event: "PreToolUse";
+}
+export declare function recordToolActivity(hqRoot: string, laneId: string, at?: string): ToolActivityRecord;
+export declare function readToolActivity(hqRoot: string, laneId: string): ToolActivityRecord | null;
+export declare function appendDropboxMessage(hqRoot: string, laneId: string, message: DropboxMessage): DropboxMessage;
+/**
+ * Drain this lane's inbox exactly once. Concurrent callers: one rename wins;
+ * the loser sees ENOENT and returns whatever it separately claimed (usually
+ * nothing). Leftovers in draining/ and dead inflight dirs are recovered.
+ */
+export declare function drainDropbox(hqRoot: string, laneId: string, depsInput?: Partial<DrainDeps>): DropboxMessage[];
+export declare function formatOperatorInstruction(messages: DropboxMessage[]): string;
+export declare function hookAdditionalContextJson(messages: DropboxMessage[]): string;
+export interface DrainHookResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Hook protocol. HQ_LANE_ID absent or empty → exit 0, empty stdout, empty stderr.
+ * That no-op is load-bearing: this hook is registered in the grok home and runs
+ * on every session on the box.
+ */
+export declare function runDrainHook(env: NodeJS.ProcessEnv): DrainHookResult;
+/** Spec §6.5: only a still-running lane gets drop-box delivery. */
+export declare function laneAcceptsDropboxDelivery(lane: Pick<LaneRecord, "state">): boolean;
+/**
+ * Operator `hq lanes message` delivery. Queued is accepted because the
+ * worker that will spawn drains the inbox on its first tool event.
+ * `laneAcceptsDropboxDelivery` refuses queued, so it is the wrong guard here.
+ */
+export declare function laneAcceptsOperatorMessage(lane: Pick<LaneRecord, "state">): boolean;
+export declare function operatorMessageRefusalReason(state: LaneState): string;
+/** Delivery target is the lane_id on the question record. Never a project/story lookup. */
+export declare function laneIdForAnswerDelivery(question: Pick<QuestionRecord, "lane_id">): string;
+export declare function answerDropboxMessage(question: Pick<QuestionRecord, "question_id" | "lane_id">, choice: string, at: string, messageId: string): DropboxMessage;
+//# sourceMappingURL=dropbox.d.ts.map