@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/dist/lib/lanes/questions.js

@@ -1,384 +0,0 @@
-/**
- * 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

@@ -1,134 +0,0 @@
-/**
- * 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