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

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

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