@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/lanes/questions.js

@@ -0,0 +1,384 @@
+/**
+ * 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 { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+import { assertNoSecretText } from "./text-scan.js";
+import { readCompaniesManifestMap } from "../work-context/repo-remote.js";
+import { appendCappedHistory, createQuestion, retryUpdateQuestion, } from "./store.js";
+import { QUESTION_BODY_STORES, } from "./types.js";
+export function assertQuestionBodySecretSafe(body) {
+    assertNoSecretText("question", body.question);
+    assertNoSecretText("context", body.context);
+    body.options.forEach((option, index) => assertNoSecretText(`option[${index}]`, option));
+    if (body.recommended !== undefined) {
+        assertNoSecretText("recommended", body.recommended);
+    }
+    if (body.notes !== undefined)
+        assertNoSecretText("answer notes", body.notes);
+}
+/** Errors that make an envelope ask unsafe or impossible to persist. */
+export function questionRecordRefusalCode(err) {
+    if (!(err instanceof LanesError))
+        return null;
+    if (err.error === "secret_text_refused" || err.error === "question_company_unavailable") {
+        return err.error;
+    }
+    return null;
+}
+export function parseQuestionBodyStore(value) {
+    if (typeof value === "string" &&
+        QUESTION_BODY_STORES.includes(value)) {
+        return value;
+    }
+    throw new LanesError("unknown_body_store", `Unknown question body store ${JSON.stringify(value)}. Accepted: ${QUESTION_BODY_STORES.join(", ")}`, { accepted: [...QUESTION_BODY_STORES], value });
+}
+export function bodyStoreForLane(lane, resolvedCompany) {
+    return lane.company || lane.mesh_company || resolvedCompany ? "company" : "personal";
+}
+export function resolveQuestionCompany(lane, activeCompany, hqRoot) {
+    const laneCompany = lane.company ?? lane.mesh_company;
+    if (laneCompany !== null && laneCompany !== undefined) {
+        return requireQuestionCompany(laneCompany, lane.lane_id, "lane");
+    }
+    if (hqRoot) {
+        const projectCompany = resolveProjectQuestionCompany(hqRoot, lane);
+        if (projectCompany)
+            return projectCompany;
+    }
+    const company = activeCompany;
+    if (!company || !company.slug.trim() || !company.uid.trim()) {
+        throw new LanesError("question_company_unavailable", `Cannot raise a question for lane ${lane.lane_id}: no lane, project, or active company could be resolved`, { lane_id: lane.lane_id, resolution: "active_company_required" });
+    }
+    return company;
+}
+function requireQuestionCompany(company, laneId, source) {
+    if (!company.slug.trim() || !company.uid.trim()) {
+        throw new LanesError("question_company_unavailable", `Cannot resolve the ${source} company for lane ${laneId}: its slug or uid is missing`, { lane_id: laneId, resolution: `${source}_company_invalid` });
+    }
+    return company;
+}
+/**
+ * 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 function resolveProjectQuestionCompany(hqRoot, lane) {
+    const projectId = lane.project_id?.trim();
+    if (!projectId)
+        return null;
+    if (projectId === "." || projectId === ".." || /[\\/\0]/.test(projectId)) {
+        throw new LanesError("question_company_unavailable", `Cannot resolve the project company for lane ${lane.lane_id}: its project id is invalid`, { lane_id: lane.lane_id, resolution: "project_id_invalid" });
+    }
+    const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+    if (!fs.existsSync(manifestPath))
+        return null;
+    const companies = readCompaniesManifestMap(hqRoot);
+    if (!companies) {
+        throw new LanesError("question_company_unavailable", `Cannot resolve the project company for lane ${lane.lane_id}: companies/manifest.yaml is unreadable or malformed`, { lane_id: lane.lane_id, resolution: "company_manifest_unavailable" });
+    }
+    const matches = [];
+    for (const [slug, entry] of Object.entries(companies)) {
+        if (!entry || typeof entry !== "object" || !slug || /[\\/\0]/.test(slug))
+            continue;
+        const projectDir = path.join(hqRoot, "companies", slug, "projects", projectId);
+        let isDirectory = false;
+        try {
+            isDirectory = fs.statSync(projectDir).isDirectory();
+        }
+        catch (err) {
+            if (err.code !== "ENOENT" && err.code !== "ENOTDIR") {
+                throw new LanesError("question_company_unavailable", `Cannot verify project ownership for lane ${lane.lane_id}`, { lane_id: lane.lane_id, resolution: "project_directory_unavailable" });
+            }
+        }
+        if (!isDirectory)
+            continue;
+        const uid = typeof entry.cloud_uid === "string" ? entry.cloud_uid.trim() : "";
+        matches.push({ slug, uid });
+    }
+    if (matches.length > 1)
+        return null;
+    const match = matches[0];
+    if (!match)
+        return null;
+    if (!match.uid) {
+        throw new LanesError("question_company_unavailable", `Cannot resolve the project company for lane ${lane.lane_id}: its manifest company has no cloud uid`, { lane_id: lane.lane_id, resolution: "project_company_uid_missing" });
+    }
+    return requireQuestionCompany({ slug: match.slug, uid: match.uid }, lane.lane_id, "project");
+}
+/** Resolve the lane/project company before lazily consulting active HQ scope. */
+export async function resolveQuestionCompanyWithFallback(hqRoot, lane, resolveActiveCompany) {
+    try {
+        return resolveQuestionCompany(lane, null, hqRoot);
+    }
+    catch (err) {
+        if (!(err instanceof LanesError) ||
+            err.error !== "question_company_unavailable" ||
+            err.details.resolution !== "active_company_required" ||
+            !resolveActiveCompany) {
+            throw err;
+        }
+        return resolveQuestionCompany(lane, await resolveActiveCompany(), hqRoot);
+    }
+}
+export function questionBodyRef(questionId) {
+    return path.posix.join("lanes", "questions", `${questionId}.json`);
+}
+export function sha256Text(text) {
+    return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+/** Tenant-store path for a question body (spec §6.2 / §10). Never the personal vault for company prose. */
+export function questionBodyAbsPath(hqRoot, question) {
+    const store = parseQuestionBodyStore(question.body.store);
+    if (store === "company") {
+        if (!question.company?.slug) {
+            throw new LanesError("question_body_store_unresolved", "Company question body is missing a company slug", { question_id: question.question_id });
+        }
+        return path.join(hqRoot, "companies", question.company.slug, "lanes", "questions", `${question.question_id}.json`);
+    }
+    return path.join(hqRoot, "personal", "lanes", "questions", `${question.question_id}.json`);
+}
+export function writeQuestionBody(hqRoot, question, body) {
+    assertQuestionBodySecretSafe(body);
+    const store = parseQuestionBodyStore(question.body.store);
+    const filePath = questionBodyAbsPath(hqRoot, question);
+    const serialized = `${JSON.stringify(body, null, 2)}\n`;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, serialized, "utf8");
+    return {
+        store,
+        ref: questionBodyRef(question.question_id),
+        digest: sha256Text(serialized),
+    };
+}
+/**
+ * Persist one question the way `hq lanes ask` does: createQuestion, write the
+ * tenant body, then CAS routing_history with reason `asked`.
+ */
+export function raiseLaneQuestion(input) {
+    assertQuestionBodySecretSafe(input.body);
+    const company = resolveQuestionCompany(input.lane, input.activeCompany, input.hqRoot);
+    const store = bodyStoreForLane(input.lane, company);
+    let questionId = input.questionId;
+    if (!questionId) {
+        const created = createQuestion(input.hqRoot, {
+            lane_id: input.lane.lane_id,
+            company,
+            project_id: input.lane.project_id,
+            story_id: input.lane.story_id,
+            thread_id: input.lane.thread_id,
+            raised_via: input.raisedVia,
+            ...(input.priority ? { priority: input.priority } : {}),
+            asked_at: input.at,
+            origin: { kind: "lane", id: input.lane.lane_id },
+            hop: 1,
+            status: "pending",
+            body: { store, ref: "", digest: "" },
+            routing_history: [],
+        });
+        questionId = created.question_id;
+    }
+    else {
+        try {
+            createQuestion(input.hqRoot, {
+                question_id: questionId,
+                lane_id: input.lane.lane_id,
+                company,
+                project_id: input.lane.project_id,
+                story_id: input.lane.story_id,
+                thread_id: input.lane.thread_id,
+                raised_via: input.raisedVia,
+                ...(input.priority ? { priority: input.priority } : {}),
+                asked_at: input.at,
+                origin: { kind: "lane", id: input.lane.lane_id },
+                hop: 1,
+                status: "pending",
+                body: { store, ref: "", digest: "" },
+                routing_history: [],
+            });
+        }
+        catch (err) {
+            if (!(err instanceof LanesError) || err.error !== "question_exists") {
+                throw err;
+            }
+        }
+    }
+    const stored = writeQuestionBody(input.hqRoot, {
+        company,
+        question_id: questionId,
+        body: { store, ref: "", digest: "" },
+    }, input.body);
+    const questionKind = classifyQuestionKind(input.body.options);
+    return retryUpdateQuestion(input.hqRoot, questionId, (current) => {
+        const asked = current.routing_history.some((entry) => entry.reason === "asked");
+        return {
+            ...current,
+            ...(questionKind !== undefined ? { question_kind: questionKind } : {}),
+            body: stored,
+            raised_via: input.raisedVia,
+            routing_history: asked
+                ? current.routing_history
+                : appendCappedHistory(current.routing_history, {
+                    hop: 1,
+                    audience: input.lane.senior,
+                    at: input.at,
+                    reason: "asked",
+                }),
+        };
+    });
+}
+/**
+ * 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 function classifyQuestionKind(options) {
+    if (options.length !== 2)
+        return undefined;
+    const folded = options.map((option) => option
+        .trim()
+        .toLowerCase()
+        .replace(/[.!?…]+$/u, "")
+        .trim());
+    const isContinueStop = folded.includes("continue") && folded.includes("stop") && folded[0] !== folded[1];
+    return isContinueStop ? "continue" : undefined;
+}
+/** The store a lane's question bodies live in, derived from the lane and never the reverse. */
+export function questionBodyPathForLane(hqRoot, lane, questionId) {
+    return questionBodyAbsPath(hqRoot, {
+        company: lane.company,
+        question_id: questionId,
+        body: { store: bodyStoreForLane(lane), ref: "", digest: "" },
+    });
+}
+/**
+ * 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 function readAnswerNotes(hqRoot, lane, question) {
+    if (!question.answer?.notes_ref)
+        return undefined;
+    const bodyStore = parseQuestionBodyStore(question.body.store);
+    const company = question.company ?? (bodyStore === "company" ? lane.company ?? lane.mesh_company ?? null : null);
+    if (bodyStore === "personal" && company !== question.company) {
+        throw new LanesError("question_answer_notes_store_mismatch", `Answer notes for question ${question.question_id} cannot use lane company attribution for a personal-store body`, { question_id: question.question_id });
+    }
+    const filePath = questionBodyAbsPath(hqRoot, { ...question, company });
+    let text;
+    try {
+        text = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new LanesError("question_answer_notes_unavailable", `Answer notes for question ${question.question_id} are unavailable on the owning host`, { question_id: question.question_id, code: err.code });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new LanesError("question_answer_notes_invalid", `Answer notes for question ${question.question_id} are not valid JSON`, { question_id: question.question_id });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new LanesError("question_answer_notes_invalid", `Answer notes for question ${question.question_id} have an invalid body`, { question_id: question.question_id });
+    }
+    const notes = parsed.notes;
+    if (typeof notes !== "string") {
+        throw new LanesError("question_answer_notes_invalid", `Answer notes for question ${question.question_id} are missing from the body`, { question_id: question.question_id });
+    }
+    return notes.length > 0 ? notes : undefined;
+}
+/**
+ * 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 function answeredQuestionEntries(hqRoot, lane, questions) {
+    return questions
+        .filter((q) => q.origin.id === lane.lane_id && q.status === "answered" && q.answer)
+        .map((q) => {
+        const entry = {
+            question_id: q.question_id,
+            choice: q.answer?.choice,
+            answered_at: q.answer?.answered_at,
+            answered_by: q.answer?.answered_by,
+        };
+        const notes = readAnswerNotes(hqRoot, lane, q);
+        if (notes !== undefined)
+            entry.notes = notes;
+        return entry;
+    });
+}
+export function markAnsweredQuestionsDelivered(hqRoot, laneId, questionIds, deliveredAt) {
+    if (!Number.isFinite(Date.parse(deliveredAt))) {
+        throw new LanesError("question_delivery_timestamp_invalid", "Cannot mark an answer delivered with an invalid timestamp", { lane_id: laneId });
+    }
+    return [...new Set(questionIds)].map((questionId) => retryUpdateQuestion(hqRoot, questionId, (current) => {
+        if (current.lane_id !== laneId || current.origin.id !== laneId) {
+            throw new LanesError("question_lane_mismatch", `Question ${questionId} does not belong to the resumed lane ${laneId}`, { lane_id: laneId, question_id: questionId });
+        }
+        if (current.status !== "answered" || !current.answer) {
+            throw new LanesError("question_not_answered", `Question ${questionId} is not answered and cannot be marked delivered`, { lane_id: laneId, question_id: questionId });
+        }
+        if (current.delivered_at)
+            return current;
+        return { ...current, delivered_at: deliveredAt };
+    }));
+}
+export function envelopeQuestionId(laneId, envelopeRef, index) {
+    const stem = path.basename(envelopeRef, ".json").replace(/[^A-Za-z0-9_-]/g, "");
+    const digest = createHash("sha256")
+        .update(`${laneId}\0${envelopeRef}\0${index}`)
+        .digest("hex")
+        .slice(0, 10);
+    return `qenv_${stem}_${index}_${digest}`;
+}
+function envelopeQuestionBody(item) {
+    const body = {
+        question: item.question,
+        context: item.context,
+        options: item.options,
+    };
+    if (item.recommended !== undefined)
+        body.recommended = item.recommended;
+    return body;
+}
+/**
+ * Spec §6.1: each envelope questions[] entry becomes one queue record, via
+ * raiseLaneQuestion (the same function the CLI ask path uses).
+ */
+export function raiseEnvelopeQuestions(hqRoot, lane, envelope, envelopeRef, at, questionIndexes, activeCompany) {
+    const items = envelope.questions ?? [];
+    const presentItems = items.filter((item) => item !== undefined);
+    if (presentItems.length === 0)
+        return [];
+    for (const item of presentItems) {
+        assertQuestionBodySecretSafe(envelopeQuestionBody(item));
+    }
+    resolveQuestionCompany(lane, activeCompany, hqRoot);
+    const raised = [];
+    for (let i = 0; i < items.length; i += 1) {
+        const item = items[i];
+        if (!item)
+            continue;
+        raised.push(raiseLaneQuestion({
+            hqRoot,
+            lane,
+            body: envelopeQuestionBody(item),
+            raisedVia: "envelope",
+            at,
+            questionId: envelopeQuestionId(lane.lane_id, envelopeRef, questionIndexes?.[i] ?? i),
+            activeCompany,
+        }));
+    }
+    return raised;
+}
+//# sourceMappingURL=questions.js.map

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

@@ -0,0 +1,134 @@
+/**
+ * Machine-written provider quota, keyed by account and model.
+ *
+ * `enabled` and `disabled_reason` live in personal/lanes/config.json and are
+ * the operator's hand-written switch. `quota_reset_at` and `needs_credits`
+ * are written here, in personal/lanes/quota.json, from the provider's own
+ * 429. They are separate fields because a quota hold expires on its own:
+ * copying it into `disabled_reason` or flipping `enabled` would erase the
+ * operator's reason, and would leave the account switched off after the
+ * provider reset. The balancer reads this file and does not rewrite the
+ * operator fields.
+ *
+ * A weekly-limit 429 names a reset and applies to every model on that
+ * account (measured: account b, every model, until the reset). A credits
+ * 429 names one model and no reset (measured: account d refuses
+ * claude-fable-5-1 and still runs claude-opus-5). The record is therefore
+ * per (account, model), plus an account-wide reset when the text is a
+ * usage limit rather than a switch-model refusal.
+ */
+import type { LaneProvider } from "./types.js";
+export declare const QUOTA_STATE_REL: string;
+export declare const QUOTA_SCHEMA_VERSION = "hq-lanes-quota.v1";
+export interface ModelQuota {
+    quota_reset_at?: string;
+    needs_credits?: boolean;
+    /** Operator-facing marker, e.g. "needs credits for claude-fable-5-1". */
+    marker?: string;
+}
+export type QuotaResetSource = "provider" | "default_hold";
+export interface AccountQuota {
+    /** Set when the 429 is an account-wide usage limit with a reset time. */
+    all_models_quota_reset_at?: string;
+    /**
+     * Where `all_models_quota_reset_at` came from: the provider's own message,
+     * or the configured default hold applied to a 429 that named no reset.
+     */
+    reset_source?: QuotaResetSource;
+    models: Record<string, ModelQuota>;
+}
+export interface QuotaState {
+    schema_version: typeof QUOTA_SCHEMA_VERSION;
+    providers: Partial<Record<LaneProvider, Record<string, AccountQuota>>>;
+}
+export interface QuotaSignal {
+    reason: "account_quota_exhausted" | "account_model_unavailable";
+    quota_reset_at?: string;
+    model?: string;
+    needs_credits?: boolean;
+    marker?: string;
+    /** True when the text is a usage limit with a reset, not a per-model credits refusal. */
+    account_wide?: boolean;
+    /** Set by applyDefaultQuotaHold: whether the reset is the provider's or the default hold. */
+    reset_source?: QuotaResetSource;
+}
+/**
+ * A 429 whose message names no reset time and no credits wording would
+ * otherwise record no hold at all, and the next lane on the account would
+ * hit the same 429. Give such a signal the provider's configured default
+ * hold (`quota_default_hold_ms`, fifteen minutes unless set) as its reset,
+ * marked `default_hold`; a signal that already carries a reset keeps it,
+ * marked `provider`. A per-model credits refusal is untouched.
+ */
+export declare function applyDefaultQuotaHold(signal: QuotaSignal, defaultHoldMs: number, now: Date): QuotaSignal;
+export declare function quotaStatePath(hqRoot: string): string;
+export declare function loadQuotaState(hqRoot: string): QuotaState;
+/**
+ * Parse provider reset times such as "resets Sep 24, 2am (UTC)" and Codex's
+ * "try again at Sep 14th, 2026 9:24 PM" into an ISO timestamp. Codex's
+ * unzoned form is displayed in the provider CLI's local timezone, while the
+ * provider `resets` form is UTC when it names `(UTC)`. The year is the current
+ * UTC year for an unyear-tagged reset, rolled forward when it is already past.
+ * An explicit provider year is kept as stated.
+ */
+export declare function parseProviderResetTime(text: string, now: Date): string | null;
+/**
+ * Read only `api_error_status`, `is_error`, and `result` off the last
+ * `type: "result"` object. Nothing else from the payload is returned, and
+ * this function does not log.
+ */
+export declare function quotaFieldsFromOutput(text: string): {
+    api_error_status: unknown;
+    is_error: unknown;
+    result: unknown;
+} | null;
+export declare function quotaSignalFromFields(fields: {
+    api_error_status: unknown;
+    is_error: unknown;
+    result: unknown;
+}, model: string | undefined, now: Date): QuotaSignal | null;
+export declare function readQuotaSignal(runDir: string, model: string | undefined, now: Date, workerOutOffset?: number): QuotaSignal | null;
+export declare function recordAccountQuota(hqRoot: string, provider: LaneProvider, accountId: string, signal: QuotaSignal): QuotaState;
+export interface ClearedModelQuotaReset {
+    model: string;
+    quota_reset_at: string;
+}
+export interface AccountQuotaClearResult {
+    all_models_quota_reset_at: string | null;
+    model_quota_resets: ClearedModelQuotaReset[];
+}
+export interface ClearAccountQuotaOptions {
+    /** Clear only this model's reset instead of every per-model reset. */
+    model?: string;
+    /** Clear only marks whose reset time is still ahead of now. */
+    futureOnly?: boolean;
+    now?: Date;
+}
+/** Clear quota reset marks and persist them with the quota file's atomic writer. */
+export declare function clearAccountQuota(hqRoot: string, provider: LaneProvider, accountId: string, options?: ClearAccountQuotaOptions): AccountQuotaClearResult;
+export declare function clearAccountQuotaAfterSuccessfulTurn(hqRoot: string, provider: LaneProvider, accountId: string, model: string, now: Date): AccountQuotaClearResult;
+export declare function clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot: string, provider: LaneProvider, accountId: string, model: string, now: Date): void;
+export interface QuotaBlock {
+    blocked: boolean;
+    reason?: "account_quota_exhausted" | "account_model_unavailable";
+    quota_reset_at?: string;
+    marker?: string;
+    model?: string;
+}
+/**
+ * Skip an account only for the models it cannot run. An account-wide reset
+ * blocks every model. A needs-credits marker blocks only that model, with
+ * no expiry. A past reset does not block.
+ */
+export declare function quotaBlockFor(state: QuotaState, provider: LaneProvider, accountId: string, model: string | undefined, now: Date): QuotaBlock;
+export interface AccountQuotaView {
+    quota_reset_at: string | null;
+    model_quota: Array<{
+        model: string;
+        quota_reset_at?: string;
+        needs_credits?: boolean;
+        marker?: string;
+    }>;
+}
+export declare function accountQuotaView(state: QuotaState, provider: LaneProvider, accountId: string): AccountQuotaView;
+//# sourceMappingURL=quota.d.ts.map