@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/lanes/provider-rejection.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Provider-level turn failures read off the worker's own stdout.
+ *
+ * A worker whose turn the provider refused (a 400 for a model the account
+ * cannot use, a 402 for an exhausted balance, a 5xx) exits with partial
+ * output and no envelope. Without this module the watcher classifies that
+ * `interrupted` with `exited_with_partial_output`, and the operator has to
+ * read the raw log to learn why. Here the failure is named: the lane is
+ * `failed` with `terminal_reason: provider_rejected` and the provider's own
+ * message on `terminal_details`.
+ *
+ * A 429 is parsed here like any other status so that a codex or grok 429,
+ * which the claude-shaped quota reader cannot see, still reaches the quota
+ * path: the watcher routes a `status === QUOTA_STATUS` failure to quota.ts
+ * (reset time, account hold) and everything else to `provider_rejected`.
+ *
+ * Only the fields named below are read out of the payload. The prompt, the
+ * response body and everything else stay on disk. Nothing here logs.
+ */
+import type { LaneProvider } from "./types.js";
+export declare const PROVIDER_REJECTED_REASON: "provider_rejected";
+/** Bytes of the provider message kept on the record. The log keeps the rest. */
+export declare const PROVIDER_REJECTION_MESSAGE_CAP = 2000;
+/** Status the watcher routes to the quota path instead of `provider_rejected`. */
+export declare const QUOTA_STATUS = 429;
+export interface ProviderRejection {
+    reason: typeof PROVIDER_REJECTED_REASON;
+    provider: LaneProvider;
+    /** The provider's error message, verbatim, capped at PROVIDER_REJECTION_MESSAGE_CAP. */
+    message: string;
+    /** HTTP status the provider reported; null when the payload named none. */
+    status: number | null;
+    /** Provider error class, e.g. `invalid_request_error`; null when absent. */
+    error_type: string | null;
+    /** Derived from the status: a transient class (408, 425, 5xx) is retryable; a 4xx is not. */
+    retryable: boolean;
+    /** Which event on the stream carried the failure. */
+    event: "codex.turn.failed" | "claude.result.is_error" | "claude.result.login_failure" | "grok.error";
+}
+export declare function isProviderLoginFailure(failure: ProviderRejection | null): boolean;
+export declare function capMessage(message: string): string;
+/**
+ * Whether a later run could succeed without the operator changing anything.
+ * A 400 model rejection cannot; a request timeout, a too-early, or a server
+ * error can. An unknown status is not retryable: guessing "try again" on a
+ * failure we cannot classify would loop the lane.
+ */
+export declare function retryableFromStatus(status: number | null): boolean;
+/**
+ * Codex `exec --json`: `{"type":"turn.failed","error":{"message":"<text>"}}`.
+ * Measured 2026-09-22 (lane 01M34HCCP1ZDN3H68ESCRZE7RZ): the message is
+ * itself a JSON string, `{"type":"error","status":400,"error":{"type":
+ * "invalid_request_error","message":"The 'terra' model is not supported when
+ * using Codex with a ChatGPT account."}}`. The inner message and status are
+ * read when it parses; otherwise the outer text is the message.
+ */
+export declare function parseCodexTurnFailed(text: string): ProviderRejection | null;
+/**
+ * Claude `-p --output-format json`: the last `type: "result"` object with
+ * `is_error: true` and a numeric `api_error_status`, or the CLI's explicit
+ * unauthenticated message. Other status-less errors keep the existing
+ * classification because they may be quota text or a worker failure.
+ */
+export declare function parseClaudeResultRejection(text: string): ProviderRejection | null;
+/**
+ * Grok `--output-format json` prints one object. Measured 2026-09-22 (lane
+ * 01M33X586J18J1B6GK0E6M4Y07): `{"type":"error","message":"Internal error:
+ * {\n  \"message\": \"API error (status 402 Payment Required): Grok Build
+ * usage balance exhausted\",\n  \"http_status\": 402, ...}", ...}`. The
+ * inner object carries `message` and `http_status`; when it does not parse,
+ * the status is read from `(status NNN` in the text.
+ */
+export declare function parseGrokErrorOutput(text: string): ProviderRejection | null;
+/** The `terminal_details` record both the watcher and the reconcile pass write for a rejection. */
+export declare function providerRejectionDetails(rejection: ProviderRejection, lane: {
+    model?: string;
+    account?: string;
+}): Record<string, unknown>;
+export declare function parseProviderRejection(provider: LaneProvider, text: string): ProviderRejection | null;
+/**
+ * Read this run's bytes of `logs/worker.out` (past `workerOutOffset`, the
+ * same cut delivery.ts uses) and return the provider rejection they carry,
+ * or null. A missing file is null; any other read error propagates.
+ */
+export declare function readProviderRejection(runDir: string, provider: LaneProvider, workerOutOffset?: number): ProviderRejection | null;
+//# sourceMappingURL=provider-rejection.d.ts.map

package/dist/lib/lanes/provider-rejection.js

@@ -0,0 +1,286 @@
+/**
+ * Provider-level turn failures read off the worker's own stdout.
+ *
+ * A worker whose turn the provider refused (a 400 for a model the account
+ * cannot use, a 402 for an exhausted balance, a 5xx) exits with partial
+ * output and no envelope. Without this module the watcher classifies that
+ * `interrupted` with `exited_with_partial_output`, and the operator has to
+ * read the raw log to learn why. Here the failure is named: the lane is
+ * `failed` with `terminal_reason: provider_rejected` and the provider's own
+ * message on `terminal_details`.
+ *
+ * A 429 is parsed here like any other status so that a codex or grok 429,
+ * which the claude-shaped quota reader cannot see, still reaches the quota
+ * path: the watcher routes a `status === QUOTA_STATUS` failure to quota.ts
+ * (reset time, account hold) and everything else to `provider_rejected`.
+ *
+ * Only the fields named below are read out of the payload. The prompt, the
+ * response body and everything else stay on disk. Nothing here logs.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const PROVIDER_REJECTED_REASON = "provider_rejected";
+/** Bytes of the provider message kept on the record. The log keeps the rest. */
+export const PROVIDER_REJECTION_MESSAGE_CAP = 2000;
+/** Status the watcher routes to the quota path instead of `provider_rejected`. */
+export const QUOTA_STATUS = 429;
+/** Exact auth failures observed from each installed CLI in an empty home. */
+function isProviderLoginMessage(provider, message) {
+    switch (provider) {
+        case "claude":
+            return /(?:\bnot logged in\b|\bplease run\s+\/login\b)/i.test(message);
+        case "codex":
+            return /\bnot logged in\b/i.test(message) ||
+                /\bmissing bearer or basic authentication in header\b/i.test(message);
+        case "grok":
+            return /^\s*not signed in\b/i.test(message);
+        default: {
+            const _exhaustive = provider;
+            return _exhaustive;
+        }
+    }
+}
+/** Successful Claude results can contain worker prose, so only accept its short CLI login banner. */
+function isClaudeSuccessLoginMessage(message) {
+    const trimmed = message.trim();
+    return trimmed.length <= 80 && /^not logged in\b.{0,40}please run \/login\.?$/i.test(trimmed);
+}
+export function isProviderLoginFailure(failure) {
+    return failure !== null && isProviderLoginMessage(failure.provider, failure.message);
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Walk the JSON lines of `text` from the last line backward, parsing one
+ * line at a time, and return the first value `pick` accepts. A long codex
+ * run writes thousands of events to worker.out; the failure, when there is
+ * one, is at the tail, so the scan stops there and never holds every parsed
+ * event at once. Lines that are not objects are skipped without parsing.
+ */
+function scanJsonLinesBackward(text, pick) {
+    let end = text.length;
+    while (end > 0) {
+        const start = text.lastIndexOf("\n", end - 1);
+        const line = text.slice(start + 1, end).trim();
+        end = start === -1 ? 0 : start;
+        if (!line.startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isPlainObject(parsed))
+            continue;
+        const picked = pick(parsed);
+        if (picked !== null)
+            return picked;
+    }
+    return null;
+}
+/** Parse the whole text as one JSON object (grok prints a single pretty-printed object). */
+function wholeObject(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{"))
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return isPlainObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+const NOT_REJECTED = Symbol("not_rejected");
+function statusOf(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599
+        ? value
+        : null;
+}
+export function capMessage(message) {
+    return message.length > PROVIDER_REJECTION_MESSAGE_CAP
+        ? `${message.slice(0, PROVIDER_REJECTION_MESSAGE_CAP)}…`
+        : message;
+}
+/**
+ * Whether a later run could succeed without the operator changing anything.
+ * A 400 model rejection cannot; a request timeout, a too-early, or a server
+ * error can. An unknown status is not retryable: guessing "try again" on a
+ * failure we cannot classify would loop the lane.
+ */
+export function retryableFromStatus(status) {
+    if (status === null)
+        return false;
+    if (status === 408 || status === 425)
+        return true;
+    return status >= 500 && status <= 599;
+}
+/**
+ * Codex `exec --json`: `{"type":"turn.failed","error":{"message":"<text>"}}`.
+ * Measured 2026-09-22 (lane 01M34HCCP1ZDN3H68ESCRZE7RZ): the message is
+ * itself a JSON string, `{"type":"error","status":400,"error":{"type":
+ * "invalid_request_error","message":"The 'terra' model is not supported when
+ * using Codex with a ChatGPT account."}}`. The inner message and status are
+ * read when it parses; otherwise the outer text is the message.
+ */
+export function parseCodexTurnFailed(text) {
+    return scanJsonLinesBackward(text, (rec) => {
+        if (rec.type !== "turn.failed")
+            return null;
+        const error = isPlainObject(rec.error) ? rec.error : {};
+        const outer = typeof error.message === "string" ? error.message : "";
+        let message = outer;
+        let status = null;
+        let errorType = null;
+        const inner = wholeObject(outer);
+        if (inner) {
+            status = statusOf(inner.status);
+            const innerError = isPlainObject(inner.error) ? inner.error : {};
+            if (typeof innerError.message === "string" && innerError.message.length > 0) {
+                message = innerError.message;
+            }
+            if (typeof innerError.type === "string")
+                errorType = innerError.type;
+        }
+        return {
+            reason: PROVIDER_REJECTED_REASON,
+            provider: "codex",
+            message: capMessage(message),
+            status,
+            error_type: errorType,
+            retryable: retryableFromStatus(status),
+            event: "codex.turn.failed",
+        };
+    });
+}
+/**
+ * Claude `-p --output-format json`: the last `type: "result"` object with
+ * `is_error: true` and a numeric `api_error_status`, or the CLI's explicit
+ * unauthenticated message. Other status-less errors keep the existing
+ * classification because they may be quota text or a worker failure.
+ */
+export function parseClaudeResultRejection(text) {
+    // The last `result` decides: a success or a status-less error there is
+    // final (NOT_REJECTED), so the scan does not continue to earlier results.
+    const found = scanJsonLinesBackward(text, (rec) => {
+        if (rec.type !== "result")
+            return null;
+        const message = typeof rec.result === "string" ? rec.result : "";
+        const loginFailure = rec.is_error === true
+            ? isProviderLoginMessage("claude", message)
+            : isClaudeSuccessLoginMessage(message);
+        if (rec.is_error !== true && !loginFailure)
+            return NOT_REJECTED;
+        const status = statusOf(rec.api_error_status);
+        if (status === null && !loginFailure)
+            return NOT_REJECTED;
+        return {
+            reason: PROVIDER_REJECTED_REASON,
+            provider: "claude",
+            message: capMessage(message),
+            status,
+            error_type: typeof rec.subtype === "string" ? rec.subtype : null,
+            retryable: retryableFromStatus(status),
+            event: loginFailure && rec.is_error !== true
+                ? "claude.result.login_failure"
+                : "claude.result.is_error",
+        };
+    });
+    return found === NOT_REJECTED ? null : found;
+}
+/**
+ * Grok `--output-format json` prints one object. Measured 2026-09-22 (lane
+ * 01M33X586J18J1B6GK0E6M4Y07): `{"type":"error","message":"Internal error:
+ * {\n  \"message\": \"API error (status 402 Payment Required): Grok Build
+ * usage balance exhausted\",\n  \"http_status\": 402, ...}", ...}`. The
+ * inner object carries `message` and `http_status`; when it does not parse,
+ * the status is read from `(status NNN` in the text.
+ */
+export function parseGrokErrorOutput(text) {
+    // One pretty-printed object is the measured shape; a line stream is the
+    // fallback, read from the tail like the other providers.
+    const whole = wholeObject(text);
+    if (whole !== null)
+        return grokRejectionFrom(whole);
+    return scanJsonLinesBackward(text, grokRejectionFrom);
+}
+function grokRejectionFrom(rec) {
+    if (rec.type !== "error")
+        return null;
+    const outer = typeof rec.message === "string" ? rec.message : "";
+    let message = outer;
+    let status = null;
+    const braceAt = outer.indexOf("{");
+    const inner = braceAt >= 0 ? wholeObject(outer.slice(braceAt)) : null;
+    if (inner) {
+        if (typeof inner.message === "string" && inner.message.length > 0) {
+            message = inner.message;
+        }
+        status = statusOf(inner.http_status);
+    }
+    if (status === null) {
+        const match = /\(status\s+(\d{3})\b/.exec(outer);
+        status = match ? statusOf(Number(match[1])) : null;
+    }
+    return {
+        reason: PROVIDER_REJECTED_REASON,
+        provider: "grok",
+        message: capMessage(message),
+        status,
+        error_type: null,
+        retryable: retryableFromStatus(status),
+        event: "grok.error",
+    };
+}
+/** The `terminal_details` record both the watcher and the reconcile pass write for a rejection. */
+export function providerRejectionDetails(rejection, lane) {
+    return {
+        reason: rejection.reason,
+        provider: rejection.provider,
+        message: rejection.message,
+        status: rejection.status,
+        error_type: rejection.error_type,
+        retryable: rejection.retryable,
+        event: rejection.event,
+        model: lane.model ?? null,
+        account: lane.account ?? null,
+    };
+}
+export function parseProviderRejection(provider, text) {
+    switch (provider) {
+        case "codex":
+            return parseCodexTurnFailed(text);
+        case "claude":
+            return parseClaudeResultRejection(text);
+        case "grok":
+            return parseGrokErrorOutput(text);
+        default: {
+            const _exhaustive = provider;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Read this run's bytes of `logs/worker.out` (past `workerOutOffset`, the
+ * same cut delivery.ts uses) and return the provider rejection they carry,
+ * or null. A missing file is null; any other read error propagates.
+ */
+export function readProviderRejection(runDir, provider, workerOutOffset = 0) {
+    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 null;
+        throw err;
+    }
+    return parseProviderRejection(provider, text);
+}
+//# sourceMappingURL=provider-rejection.js.map

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

@@ -0,0 +1,90 @@
+/**
+ * Raise a lane question (spec §6.1). One function for the CLI `hq lanes ask`
+ * path and for envelope `decision: "ask"` ingestion. Two writers here would
+ * drift on hop, origin, raised_via, body store, and routing_history.
+ */
+import { type LaneEnvelope, type LaneRecord, type LaneCompanyRef, type QuestionBodyStore, type QuestionKind, type QuestionPriority, type QuestionRecord, type RaisedVia } from "./types.js";
+export interface QuestionBody {
+    question: string;
+    context: string;
+    options: string[];
+    recommended?: string;
+    notes?: string;
+}
+export declare function assertQuestionBodySecretSafe(body: QuestionBody): void;
+/** Errors that make an envelope ask unsafe or impossible to persist. */
+export declare function questionRecordRefusalCode(err: unknown): "secret_text_refused" | "question_company_unavailable" | null;
+export declare function parseQuestionBodyStore(value: unknown): QuestionBodyStore;
+export declare function bodyStoreForLane(lane: Pick<LaneRecord, "company" | "mesh_company">, resolvedCompany?: LaneCompanyRef): QuestionBodyStore;
+export declare function resolveQuestionCompany(lane: Pick<LaneRecord, "lane_id" | "company" | "mesh_company" | "project_id">, activeCompany?: LaneCompanyRef | null, hqRoot?: string): LaneCompanyRef;
+/**
+ * Resolve project ownership only when exactly one manifest company contains
+ * the project's directory. Multiple matches are unresolved so the caller can
+ * continue to an explicit active-company choice without picking an owner.
+ */
+export declare function resolveProjectQuestionCompany(hqRoot: string, lane: Pick<LaneRecord, "lane_id" | "project_id">): LaneCompanyRef | null;
+/** Resolve the lane/project company before lazily consulting active HQ scope. */
+export declare function resolveQuestionCompanyWithFallback(hqRoot: string, lane: Pick<LaneRecord, "lane_id" | "company" | "mesh_company" | "project_id">, resolveActiveCompany?: () => Promise<LaneCompanyRef | null>): Promise<LaneCompanyRef>;
+export declare function questionBodyRef(questionId: string): string;
+export declare function sha256Text(text: string): string;
+/** Tenant-store path for a question body (spec §6.2 / §10). Never the personal vault for company prose. */
+export declare function questionBodyAbsPath(hqRoot: string, question: Pick<QuestionRecord, "company" | "body" | "question_id">): string;
+export declare function writeQuestionBody(hqRoot: string, question: Pick<QuestionRecord, "company" | "body" | "question_id">, body: QuestionBody): {
+    store: QuestionBodyStore;
+    ref: string;
+    digest: string;
+};
+export interface RaiseLaneQuestionInput {
+    hqRoot: string;
+    lane: LaneRecord;
+    body: QuestionBody;
+    raisedVia: RaisedVia;
+    at: string;
+    activeCompany?: LaneCompanyRef | null;
+    questionId?: string;
+    priority?: QuestionPriority;
+}
+/**
+ * Persist one question the way `hq lanes ask` does: createQuestion, write the
+ * tenant body, then CAS routing_history with reason `asked`.
+ */
+export declare function raiseLaneQuestion(input: RaiseLaneQuestionInput): QuestionRecord;
+/**
+ * Options that, trimmed, case-folded and stripped of trailing punctuation,
+ * are exactly {continue, stop} in either order. The brief authorises the work
+ * it lists, so this question asks the operator nothing the brief did not
+ * already settle; it is recorded as `question_kind: "continue"`.
+ */
+export declare function classifyQuestionKind(options: readonly string[]): QuestionKind | undefined;
+/** The store a lane's question bodies live in, derived from the lane and never the reverse. */
+export declare function questionBodyPathForLane(hqRoot: string, lane: Pick<LaneRecord, "company" | "mesh_company">, questionId: string): string;
+/**
+ * Free-text notes the operator attached with `questions answer --notes`.
+ * Read from the lane's own store (spec §6.5): the company store for a company
+ * lane, the personal store otherwise. Returns undefined when the answer has
+ * no notes_ref or the body carries no notes. An unavailable or malformed body
+ * fails the resume so the lane cannot continue without its answer notes.
+ */
+export declare function readAnswerNotes(hqRoot: string, lane: Pick<LaneRecord, "company" | "mesh_company">, question: Pick<QuestionRecord, "question_id" | "company" | "body" | "answer">): string | undefined;
+export interface AnsweredQuestionEntry {
+    question_id: string;
+    choice: string | undefined;
+    answered_at: string | undefined;
+    answered_by: string | undefined;
+    notes?: string;
+}
+/**
+ * The `answered-questions.json` a resumed worker is handed (spec §6.5). Ids,
+ * choices and timestamps come from the routing record; the operator's notes
+ * come from the lane's own body store and are written only into the run
+ * directory on the executing host.
+ */
+export declare function answeredQuestionEntries(hqRoot: string, lane: Pick<LaneRecord, "lane_id" | "company">, questions: QuestionRecord[]): AnsweredQuestionEntry[];
+export declare function markAnsweredQuestionsDelivered(hqRoot: string, laneId: string, questionIds: readonly string[], deliveredAt: string): QuestionRecord[];
+export declare function envelopeQuestionId(laneId: string, envelopeRef: string, index: number): string;
+/**
+ * Spec §6.1: each envelope questions[] entry becomes one queue record, via
+ * raiseLaneQuestion (the same function the CLI ask path uses).
+ */
+export declare function raiseEnvelopeQuestions(hqRoot: string, lane: LaneRecord, envelope: LaneEnvelope, envelopeRef: string, at: string, questionIndexes?: readonly number[], activeCompany?: LaneCompanyRef | null): QuestionRecord[];
+//# sourceMappingURL=questions.d.ts.map