@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/lanes/mesh-events.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 { LanesError } from "./errors.js";
+import type { LaneCompanyRef, LaneEnvelope, LaneRecord, TerminalLaneState } from "./types.js";
+export declare const LANE_MESH_EVENTS: readonly ["lane_started", "lane_progress", "lane_question", "lane_question_at_user", "lane_ask", "lane_blocked", "lane_done", "lane_failed", "lane_interrupted", "lane_cancelled", "lane_killed"];
+export type LaneMeshEvent = (typeof LANE_MESH_EVENTS)[number];
+/** Roster kinds this module emits. Subset of the server's `validKinds`. */
+export declare const WIRE_EVENT_KINDS: readonly ["run_started", "run_progress", "run_complete", "blocked", "question", "note"];
+export type WireEventKind = (typeof WIRE_EVENT_KINDS)[number];
+/** Server caps: activity title/summary 2000, question text 500, note text 500. */
+export declare const WIRE_ACTIVITY_TEXT_MAX = 2000;
+export declare const WIRE_QUESTION_TEXT_MAX = 500;
+export declare const WIRE_NOTE_TEXT_MAX = 500;
+export interface WireThreadEvent {
+    eventKind: WireEventKind;
+    payload: Record<string, unknown>;
+}
+export declare function parseLaneMeshEvent(value: unknown): LaneMeshEvent;
+/**
+ * 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 declare function toWireThreadEvent(event: LaneMeshEvent, payload: Record<string, unknown>): WireThreadEvent;
+/**
+ * The seam every lane emitter goes through. `appendThreadEvent` takes the
+ * spec's lane event name; the default implementation maps it to the wire
+ * kind. Tests substitute a recording implementation and see lane names.
+ */
+export interface LaneMesh {
+    ensureProjectThread: (company: LaneCompanyRef, projectId: string) => Promise<string>;
+    ensureLaneThread?: (company: LaneCompanyRef, lane: LaneRecord, laneStatus?: string, signal?: AbortSignal) => Promise<string>;
+    appendThreadEvent: (company: LaneCompanyRef, threadId: string, event: LaneMeshEvent, payload: Record<string, unknown>, signal?: AbortSignal) => Promise<void>;
+    patchStoryStatus: (company: LaneCompanyRef, projectId: string, storyId: string, status: string) => Promise<void>;
+    /** Read-only Board membership check before a command writes lane state. */
+    assertProjectStoriesOnBoard?: (company: LaneCompanyRef, projectId: string, storyIds: readonly string[]) => Promise<void>;
+}
+export interface CreateLaneMeshOptions {
+    /** False for detached callers (the watcher). See the token note above. */
+    interactive?: boolean;
+    /** Test seam. Defaults to the shared `requireToken`. */
+    token?: () => Promise<string>;
+    /** Repair a missing project view before retrying a story status patch. */
+    repairProjectView?: (input: {
+        token: string;
+        company: LaneCompanyRef;
+        projectId: string;
+        storyId: string;
+        status: string;
+    }) => Promise<void>;
+}
+export declare function storyNotOnBoardError(company: LaneCompanyRef, projectId: string, storyId: string): LanesError;
+export declare function laneStoryStatusSuppressionKey(company: LaneCompanyRef, projectId: string, storyId: string): string;
+export declare function createLaneMesh(opts?: CreateLaneMeshOptions): LaneMesh;
+/** Resolve the explicit mesh attribution before falling back to the lane tenant. */
+export declare function laneMeshCompany(lane: Pick<LaneRecord, "company" | "mesh_company">): LaneCompanyRef | undefined;
+/** Company attribution + thread present. Unscoped personal lanes emit nothing. */
+export declare function laneCanEmit(lane: Pick<LaneRecord, "company" | "mesh_company" | "thread_id">): boolean;
+export declare function laneMeshEventIdentity(lane: LaneRecord): Record<string, unknown>;
+/**
+ * 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 declare function emitLaneDecisionEvents(mesh: LaneMesh, lane: LaneRecord, envelope: Pick<LaneEnvelope, "decision" | "summary" | "blocked_reason">, opts?: {
+    questionIds?: string[];
+    signal?: AbortSignal;
+    /** Per-watcher-run cache for story_not_on_board refusals. */
+    storyStatusSuppressions?: Set<string>;
+}): Promise<void>;
+/** Emit an abnormal terminal state even when the worker produced no envelope. */
+export declare function emitLaneTerminalStateEvent(mesh: LaneMesh, lane: LaneRecord, state: Exclude<TerminalLaneState, "done">, summary?: string, signal?: AbortSignal): Promise<void>;
+export declare function emitLaneProgressEvent(mesh: LaneMesh, lane: LaneRecord, detail: string, signal?: AbortSignal): Promise<void>;
+/**
+ * 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 declare function progressEventDue(input: {
+    lastEmitMs: number | null;
+    nowMs: number;
+    minIntervalMs: number;
+}): boolean;
+//# sourceMappingURL=mesh-events.d.ts.map