@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/dist/lib/lanes/mesh-events.js

@@ -0,0 +1,275 @@
+/**
+ * Lane → work mesh events (spec §8).
+ *
+ * The lane side speaks the spec's vocabulary: lane_started, lane_progress,
+ * lane_question, lane_question_at_user, lane_ask, lane_blocked, lane_done.
+ * The work-mesh append endpoint accepts a closed roster of event kinds
+ * (hq-pro `src/vault-service/handlers/work-mesh.ts`, `validKinds`) and
+ * strips every payload field its per-kind validator does not name
+ * (hq-pro `src/vault-service/work-mesh/events.ts`). A `lane_*` kind on the
+ * wire is a 400. `toWireThreadEvent` is therefore the single place that
+ * turns a lane event into a roster kind whose payload carries the lane
+ * identity in the text fields the server keeps.
+ *
+ * Mapping, and why each kind:
+ *
+ * | lane event             | wire kind      | server effect                    |
+ * |------------------------|----------------|----------------------------------|
+ * | lane_started           | run_started    | status-neutral activity          |
+ * | lane_progress          | run_progress   | status-neutral activity          |
+ * | lane_done              | run_complete   | status-neutral; story → review   |
+ * | lane_blocked           | note (system)  | status-neutral; the project      |
+ * |                        |                | thread is shared by every lane,  |
+ * |                        |                | so one lane must not flip it to  |
+ * |                        |                | `blocked` (spec §8 keeps thread  |
+ * |                        |                | status out of lane events). The  |
+ * |                        |                | payload carries `blocked: true`  |
+ * |                        |                | and `blocked_reason` for filters |
+ * | lane_question          | question       | status-neutral, carries the id   |
+ * | lane_question_at_user  | question       | same                             |
+ * | lane_ask               | question       | same; ids of the ask envelope    |
+ *
+ * Token source for detached emitters (the per-lane watcher): the same
+ * `requireToken()` every `hq mesh session … --enqueue` hook call uses,
+ * which is `ensureCognitoToken()` over the person cache at
+ * `~/.hq/cognito-tokens.json`, or a machine mint when
+ * `HQ_MACHINE_CREDS_FILE` / the default agent creds file is readable
+ * (`src/utils/cognito-session.ts`). The watcher inherits the creator's
+ * `HOME` (spawn.ts `armLaneWatcher` copies the caller env and only adds
+ * `HQ_ROOT` / `HQ_LANE_ID`; the provider account home rides its own
+ * variable, never `HOME`), so it reads the same cache the hooks read. It
+ * passes `interactive: false`: a cache that cannot refresh throws instead
+ * of opening a browser nobody is watching, and the watcher records
+ * `mesh_event_failed` and moves on. No credential file is read here.
+ */
+import { appendThreadEvent, clamp, ensureProjectThread, patchStoryStatus, requireToken, resolveMeshCompany, } from "../mesh/api.js";
+import { LanesError } from "./errors.js";
+export const LANE_MESH_EVENTS = [
+    "lane_started",
+    "lane_progress",
+    "lane_question",
+    "lane_question_at_user",
+    "lane_ask",
+    "lane_blocked",
+    "lane_done",
+];
+/** Roster kinds this module emits. Subset of the server's `validKinds`. */
+export const WIRE_EVENT_KINDS = [
+    "run_started",
+    "run_progress",
+    "run_complete",
+    "question",
+    "note",
+];
+/** Server caps: activity title/summary 2000, question text 500, note text 500. */
+export const WIRE_ACTIVITY_TEXT_MAX = 2000;
+export const WIRE_QUESTION_TEXT_MAX = 500;
+export const WIRE_NOTE_TEXT_MAX = 500;
+export function parseLaneMeshEvent(value) {
+    if (typeof value === "string" &&
+        LANE_MESH_EVENTS.includes(value)) {
+        return value;
+    }
+    throw new LanesError("unknown_lane_mesh_event", `Unknown lane mesh event ${JSON.stringify(value)}. Accepted: ${LANE_MESH_EVENTS.join(", ")}`, { accepted: [...LANE_MESH_EVENTS], value });
+}
+function str(value) {
+    if (value === undefined || value === null)
+        return "";
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function identity(payload) {
+    const lane = str(payload.lane_id) || "unknown-lane";
+    const project = str(payload.project_id);
+    const story = str(payload.story_id);
+    return project || story ? `${lane} ${project}/${story}` : lane;
+}
+function nonEmpty(text, fallback) {
+    return text.trim().length > 0 ? text : fallback;
+}
+/**
+ * Lane event → roster kind + validator-shaped payload. Pure. Every text
+ * field is pre-clamped to the server cap so a long summary is truncated
+ * here rather than rejected there.
+ */
+export function toWireThreadEvent(event, payload) {
+    const kind = parseLaneMeshEvent(event);
+    const id = identity(payload);
+    switch (kind) {
+        case "lane_started":
+            return {
+                eventKind: "run_started",
+                payload: {
+                    title: clamp(`lane_started ${str(payload.lane_id) || "unknown-lane"}`, WIRE_ACTIVITY_TEXT_MAX),
+                    summary: clamp(`Lane ${id} started`, WIRE_ACTIVITY_TEXT_MAX),
+                },
+            };
+        case "lane_progress": {
+            const detail = str(payload.detail);
+            return {
+                eventKind: "run_progress",
+                payload: {
+                    summary: clamp(nonEmpty(`lane_progress ${id}${detail ? `: ${detail}` : ""}`, "lane_progress"), WIRE_ACTIVITY_TEXT_MAX),
+                },
+            };
+        }
+        case "lane_done": {
+            const summary = str(payload.summary);
+            return {
+                eventKind: "run_complete",
+                payload: {
+                    title: clamp(`lane_done ${str(payload.lane_id) || "unknown-lane"}`, WIRE_ACTIVITY_TEXT_MAX),
+                    summary: clamp(nonEmpty(`${id}: ${summary}`.replace(/:\s*$/, ""), `lane_done ${id}`), WIRE_ACTIVITY_TEXT_MAX),
+                },
+            };
+        }
+        case "lane_blocked": {
+            const reason = str(payload.blocked_reason);
+            // The roster's `blocked` event kind would flip the shared project
+            // thread, which spec §8 keeps lane events away from. Use the accepted
+            // audit note kind to preserve a filterable blocked marker.
+            return {
+                eventKind: "note",
+                payload: {
+                    text: clamp(`lane_blocked ${id}${reason ? `: ${reason}` : ""}`, WIRE_NOTE_TEXT_MAX),
+                    noteKind: "audit",
+                },
+            };
+        }
+        case "lane_question":
+        case "lane_question_at_user": {
+            const questionId = str(payload.question_id);
+            const hop = payload.hop === undefined ? "" : ` hop ${str(payload.hop)}`;
+            const out = {
+                text: clamp(`${kind} ${id}${hop}`, WIRE_QUESTION_TEXT_MAX),
+            };
+            if (questionId)
+                out.questionId = questionId;
+            return { eventKind: "question", payload: out };
+        }
+        case "lane_ask": {
+            const ids = Array.isArray(payload.question_ids)
+                ? payload.question_ids.map((item) => str(item)).filter(Boolean)
+                : [];
+            const out = {
+                text: clamp(`lane_ask ${id}: ${ids.length} question${ids.length === 1 ? "" : "s"}${ids.length ? ` ${ids.join(" ")}` : ""}`, WIRE_QUESTION_TEXT_MAX),
+            };
+            if (ids[0])
+                out.questionId = ids[0];
+            return { eventKind: "question", payload: out };
+        }
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+}
+export function createLaneMesh(opts = {}) {
+    const interactive = opts.interactive ?? true;
+    const token = opts.token ?? (() => requireToken({ interactive }));
+    return {
+        async ensureProjectThread(company, projectId) {
+            const tok = await token();
+            const resolved = await resolveMeshCompany(tok, company.slug);
+            const ensured = await ensureProjectThread(tok, resolved, projectId, {
+                summary: `HQ lane ${projectId}`,
+            });
+            return ensured.threadId;
+        },
+        async appendThreadEvent(company, threadId, event, payload, signal) {
+            const wire = toWireThreadEvent(event, payload);
+            const tok = await token();
+            await appendThreadEvent(tok, company.uid, threadId, wire.eventKind, wire.payload, signal);
+        },
+        async patchStoryStatus(company, projectId, storyId, status) {
+            const tok = await token();
+            await patchStoryStatus(tok, company.uid, projectId, storyId, status);
+        },
+    };
+}
+/** Company + thread present. A core/personal lane (company null) emits nothing. */
+export function laneCanEmit(lane) {
+    return lane.company !== null && lane.company !== undefined && !!lane.thread_id;
+}
+function baseIdentity(lane) {
+    return {
+        lane_id: lane.lane_id,
+        project_id: lane.project_id,
+        story_id: lane.story_id,
+    };
+}
+/**
+ * Spec §8 terminal-envelope events. `done` → lane_done and story → review;
+ * `blocked` → lane_blocked; `ask` → lane_ask with the queue ids. The story is
+ * never set to `done` here: promotion belongs to the senior.
+ */
+export async function emitLaneDecisionEvents(mesh, lane, envelope, opts = {}) {
+    if (!laneCanEmit(lane))
+        return;
+    const company = lane.company;
+    const threadId = lane.thread_id;
+    switch (envelope.decision) {
+        case "done": {
+            const outcomes = await Promise.allSettled([
+                mesh.appendThreadEvent(company, threadId, "lane_done", {
+                    ...baseIdentity(lane),
+                    summary: envelope.summary,
+                }, opts.signal),
+                mesh.patchStoryStatus(company, lane.project_id, lane.story_id, "review"),
+            ]);
+            const failure = outcomes.find((outcome) => outcome.status === "rejected");
+            if (failure?.status === "rejected")
+                throw failure.reason;
+            return;
+        }
+        case "blocked":
+            await mesh.appendThreadEvent(company, threadId, "lane_blocked", {
+                ...baseIdentity(lane),
+                blocked_reason: envelope.blocked_reason ?? "",
+            });
+            return;
+        case "ask":
+            // A mesh question event has one `questionId`; sending one event per id
+            // avoids silently losing ids when the display text reaches its wire cap.
+            {
+                const failures = [];
+                for (const questionId of opts.questionIds ?? []) {
+                    try {
+                        await mesh.appendThreadEvent(company, threadId, "lane_ask", {
+                            ...baseIdentity(lane),
+                            question_ids: [questionId],
+                        }, opts.signal);
+                    }
+                    catch (err) {
+                        failures.push(err);
+                    }
+                }
+                if (failures.length > 0)
+                    throw failures[0];
+            }
+            return;
+        default: {
+            const _exhaustive = envelope.decision;
+            return _exhaustive;
+        }
+    }
+}
+export async function emitLaneProgressEvent(mesh, lane, detail, signal) {
+    if (!laneCanEmit(lane))
+        return;
+    await mesh.appendThreadEvent(lane.company, lane.thread_id, "lane_progress", {
+        ...baseIdentity(lane),
+        detail,
+    }, signal);
+}
+/**
+ * Throttle for lane_progress (spec §8 progress row). True when no progress
+ * event has been sent yet, or the last one is at least `minIntervalMs` old.
+ * The caller only asks on a tick that saw new activity; a silent tick never
+ * reaches this function.
+ */
+export function progressEventDue(input) {
+    if (input.lastEmitMs === null)
+        return true;
+    return input.nowMs - input.lastEmitMs >= input.minIntervalMs;
+}
+//# sourceMappingURL=mesh-events.js.map

package/dist/lib/lanes/outpost-dispatch.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Push an Outpost-targeted lane through `hq outposts exec` (spec §5.2).
+ *
+ * The transport is the existing OutpostsClient submit/wait pair — the same
+ * path as `hq outposts exec --async`. Create stages a payload, then runs
+ * `hq lanes pickup --payload-url` on the box. A submit or wait failure is
+ * `outpost_dispatch_failed`, never a queued lane nobody will pick up.
+ */
+import { OutpostsClient } from "@indigoai-us/hq-cloud/outposts";
+import type { LaneRecord } from "./types.js";
+export declare const PICKUP_EXEC_TIMEOUT_SECONDS = 120;
+export declare const PICKUP_WAIT_MS: number;
+export interface OutpostPickupPayload {
+    lane: LaneRecord;
+    brief: string;
+    timeout?: {
+        timeout_secs: number;
+        deadline_at: string;
+    };
+}
+export interface OutpostDispatchResult {
+    commandId: string;
+    status: string;
+    done?: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+export interface OutpostExecPort {
+    stageExecInput: (outpostId?: string) => Promise<{
+        putUrl: string;
+        getUrl: string;
+    }>;
+    submitExec: (command: string, outpostId?: string, timeoutSeconds?: number) => Promise<{
+        commandId: string;
+    }>;
+    waitForExecResult: (commandId: string, outpostId?: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        status: string;
+        done: boolean;
+        exitCode?: number | null;
+        stdout?: string;
+        stderr?: string;
+    }>;
+}
+export declare function parseOutpostPickupPayload(raw: unknown): OutpostPickupPayload;
+/** Same wrapping `hq outposts exec` applies: run from the box's HQ folder. */
+export declare function buildOutpostPickupCommand(payloadUrl: string): string;
+export declare function stageOutpostPayload(port: Pick<OutpostExecPort, "stageExecInput">, outpostId: string, bytes: Uint8Array, put?: typeof fetch): Promise<{
+    getUrl: string;
+}>;
+export declare function dispatchOutpostPickup(port: OutpostExecPort, input: {
+    outpostId: string;
+    command: string;
+    timeoutSeconds?: number;
+    waitMs?: number;
+}): Promise<OutpostDispatchResult>;
+export declare function dispatchErrorMessage(err: unknown): string;
+/** Factory matching `hq outposts exec`'s client wiring. */
+export declare function createOutpostsClient(opts: {
+    transport: ConstructorParameters<typeof OutpostsClient>[0]["transport"];
+    token: ConstructorParameters<typeof OutpostsClient>[0]["token"];
+}): OutpostsClient;
+//# sourceMappingURL=outpost-dispatch.d.ts.map

package/dist/lib/lanes/outpost-dispatch.js

@@ -0,0 +1,90 @@
+/**
+ * Push an Outpost-targeted lane through `hq outposts exec` (spec §5.2).
+ *
+ * The transport is the existing OutpostsClient submit/wait pair — the same
+ * path as `hq outposts exec --async`. Create stages a payload, then runs
+ * `hq lanes pickup --payload-url` on the box. A submit or wait failure is
+ * `outpost_dispatch_failed`, never a queued lane nobody will pick up.
+ */
+import { OutpostsClient, joinCommandParts, withRemoteHqDir } from "@indigoai-us/hq-cloud/outposts";
+import { LanesError } from "./errors.js";
+export const PICKUP_EXEC_TIMEOUT_SECONDS = 120;
+export const PICKUP_WAIT_MS = PICKUP_EXEC_TIMEOUT_SECONDS * 1000;
+export function parseOutpostPickupPayload(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new LanesError("outpost_payload_invalid", "Outpost pickup payload must be a JSON object", {});
+    }
+    const body = raw;
+    if (body.lane === null || typeof body.lane !== "object" || Array.isArray(body.lane)) {
+        throw new LanesError("outpost_payload_invalid", "Outpost pickup payload.lane must be an object", {});
+    }
+    if (typeof body.brief !== "string") {
+        throw new LanesError("outpost_payload_invalid", "Outpost pickup payload.brief must be a string", {});
+    }
+    let timeout;
+    if (body.timeout !== undefined && body.timeout !== null) {
+        if (typeof body.timeout !== "object" || Array.isArray(body.timeout)) {
+            throw new LanesError("outpost_payload_invalid", "Outpost pickup payload.timeout must be an object", {});
+        }
+        const t = body.timeout;
+        if (typeof t.timeout_secs !== "number" || typeof t.deadline_at !== "string") {
+            throw new LanesError("outpost_payload_invalid", "Outpost pickup payload.timeout needs timeout_secs and deadline_at", {});
+        }
+        timeout = { timeout_secs: t.timeout_secs, deadline_at: t.deadline_at };
+    }
+    return {
+        lane: body.lane,
+        brief: body.brief,
+        timeout,
+    };
+}
+/** Same wrapping `hq outposts exec` applies: run from the box's HQ folder. */
+export function buildOutpostPickupCommand(payloadUrl) {
+    return withRemoteHqDir(joinCommandParts(["hq", "lanes", "pickup", "--payload-url", payloadUrl]));
+}
+export async function stageOutpostPayload(port, outpostId, bytes, put = fetch) {
+    const staged = await port.stageExecInput(outpostId);
+    const upload = await put(staged.putUrl, {
+        method: "PUT",
+        headers: { "Content-Length": String(bytes.byteLength) },
+        body: bytes,
+    });
+    if (!upload.ok) {
+        throw new LanesError("outpost_dispatch_failed", `Could not upload lane payload: HTTP ${upload.status}`, { status: upload.status, outpost_id: outpostId });
+    }
+    return { getUrl: staged.getUrl };
+}
+export async function dispatchOutpostPickup(port, input) {
+    const submitted = await port.submitExec(input.command, input.outpostId, input.timeoutSeconds ?? PICKUP_EXEC_TIMEOUT_SECONDS);
+    const ac = new AbortController();
+    const waitMs = input.waitMs ?? PICKUP_WAIT_MS;
+    const timer = setTimeout(() => ac.abort(), waitMs);
+    try {
+        const result = await port.waitForExecResult(submitted.commandId, input.outpostId, { signal: ac.signal });
+        return {
+            commandId: submitted.commandId,
+            status: result.status,
+            done: result.done,
+            exitCode: result.exitCode ?? null,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+        };
+    }
+    catch (err) {
+        if (ac.signal.aborted) {
+            throw new LanesError("outpost_dispatch_failed", `Timed out waiting for Outpost pickup (${waitMs}ms)`, { outpost_id: input.outpostId, command_id: submitted.commandId });
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function dispatchErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Factory matching `hq outposts exec`'s client wiring. */
+export function createOutpostsClient(opts) {
+    return new OutpostsClient(opts);
+}
+//# sourceMappingURL=outpost-dispatch.js.map

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

@@ -0,0 +1,75 @@
+/**
+ * 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 QuestionBodyStore, type QuestionKind, type QuestionRecord, type RaisedVia } from "./types.js";
+export interface QuestionBody {
+    question: string;
+    context: string;
+    options: string[];
+    recommended?: string;
+    notes?: string;
+}
+export declare function parseQuestionBodyStore(value: unknown): QuestionBodyStore;
+export declare function bodyStoreForLane(lane: Pick<LaneRecord, "company">): QuestionBodyStore;
+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;
+    questionId?: string;
+}
+/**
+ * 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">, 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; a body the host cannot read is
+ * reported and skipped rather than failing the resume.
+ */
+export declare function readAnswerNotes(hqRoot: string, lane: Pick<LaneRecord, "company">, question: Pick<QuestionRecord, "question_id" | "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 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): QuestionRecord[];
+//# sourceMappingURL=questions.d.ts.map