@indigoai-us/hq-cli 5.125.0 → 5.127.0

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

@@ -0,0 +1,535 @@
+/**
+ * Lane record, question routing record, envelope, and config types (spec §3,
+ * §4, §5.5, §6.2). Finite sets are string-literal unions plus `const` arrays
+ * so the command layer can validate flags explicitly.
+ */
+export declare const LANE_SCHEMA_VERSION: "hq-lane.v1";
+export declare const QUESTION_SCHEMA_VERSION: "hq-lane-question.v1";
+export declare const ENVELOPE_SCHEMA_VERSION: "hq-lane-envelope.v1";
+export declare const CONFIG_SCHEMA_VERSION: "hq-lanes-config.v1";
+/**
+ * The envelope contract as a JSON schema. `parseLaneEnvelope` is the runtime
+ * check; this is the text handed to a worker on the repair turn (spec §4) so
+ * the two never drift apart in what they name.
+ */
+export declare const LANE_ENVELOPE_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "hq-lane-envelope.v1";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schema_version", "decision", "summary", "story_status", "artifacts"];
+    readonly properties: {
+        readonly schema_version: {
+            readonly const: "hq-lane-envelope.v1";
+        };
+        readonly decision: {
+            readonly enum: readonly ["done", "ask", "blocked"];
+        };
+        readonly summary: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly questions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["question", "context", "options"];
+                readonly properties: {
+                    readonly question: {
+                        readonly type: "string";
+                    };
+                    readonly context: {
+                        readonly type: "string";
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly recommended: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly story_status: {
+            readonly enum: readonly ["queued", "in_progress", "review", "done"];
+        };
+        readonly artifacts: {
+            readonly type: "array";
+        };
+        readonly blocked_reason: {
+            readonly type: "string";
+        };
+        readonly story_complete: {
+            readonly type: "boolean";
+        };
+        readonly story_complete_reason: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+    };
+    readonly allOf: readonly [{
+        readonly if: {
+            readonly properties: {
+                readonly decision: {
+                    readonly const: "ask";
+                };
+            };
+        };
+        readonly then: {
+            readonly required: readonly ["questions"];
+            readonly properties: {
+                readonly questions: {
+                    readonly minItems: 1;
+                };
+            };
+        };
+        readonly else: {
+            readonly not: {
+                readonly required: readonly ["questions"];
+            };
+        };
+    }, {
+        readonly if: {
+            readonly properties: {
+                readonly decision: {
+                    readonly const: "blocked";
+                };
+            };
+        };
+        readonly then: {
+            readonly required: readonly ["blocked_reason"];
+            readonly properties: {
+                readonly blocked_reason: {
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly else: {
+            readonly not: {
+                readonly required: readonly ["blocked_reason"];
+            };
+        };
+    }, {
+        readonly if: {
+            readonly required: readonly ["story_complete"];
+            readonly properties: {
+                readonly story_complete: {
+                    readonly const: true;
+                };
+            };
+        };
+        readonly then: {
+            readonly required: readonly ["story_complete_reason"];
+            readonly properties: {
+                readonly story_status: {
+                    readonly const: "done";
+                };
+                readonly story_complete_reason: {
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly else: {
+            readonly if: {
+                readonly required: readonly ["story_complete"];
+            };
+            readonly then: {
+                readonly required: readonly ["story_complete_reason"];
+                readonly properties: {
+                    readonly story_status: {
+                        readonly not: {
+                            readonly const: "done";
+                        };
+                    };
+                    readonly story_complete_reason: {
+                        readonly minLength: 1;
+                    };
+                };
+            };
+            readonly else: {
+                readonly not: {
+                    readonly required: readonly ["story_complete_reason"];
+                };
+            };
+        };
+    }];
+    readonly description: string;
+};
+export declare const LANE_STATES: readonly ["queued", "running", "awaiting_input", "blocked", "done", "failed", "interrupted", "cancelled", "killed"];
+export type LaneState = (typeof LANE_STATES)[number];
+/** Exact terminal set from spec §6.7. `awaiting_input` and `blocked` are not terminal. */
+export declare const TERMINAL_LANE_STATES: readonly ["done", "failed", "interrupted", "cancelled", "killed"];
+export type TerminalLaneState = (typeof TERMINAL_LANE_STATES)[number];
+export declare const LANE_PROVIDERS: readonly ["claude", "codex", "grok"];
+export type LaneProvider = (typeof LANE_PROVIDERS)[number];
+export declare const QUEUED_REASONS: readonly ["cap", "queue_position", "throttle", "provider_binary_missing"];
+export type QueuedReason = (typeof QUEUED_REASONS)[number];
+export declare const HOST_KINDS: readonly ["local", "outpost"];
+export type HostKind = (typeof HOST_KINDS)[number];
+export declare const SENIOR_KINDS: readonly ["session", "lane", "user"];
+export type SeniorKind = (typeof SENIOR_KINDS)[number];
+export declare const ENVELOPE_DECISIONS: readonly ["done", "ask", "blocked"];
+export type EnvelopeDecision = (typeof ENVELOPE_DECISIONS)[number];
+export declare const STORY_STATUSES: readonly ["queued", "in_progress", "review", "done"];
+export type StoryStatus = (typeof STORY_STATUSES)[number];
+/**
+ * `expired` is accepted on read for records that already carry it. Spec §9
+ * ageing advances hop with `unanswered_timeout` and never expires a question,
+ * so reconcile (the only writer that may age without an operator) does not
+ * write this value. Kept in the enum so `--status expired` and old files parse.
+ */
+export declare const QUESTION_STATUSES: readonly ["pending", "answered", "cancelled", "expired"];
+export type QuestionStatus = (typeof QUESTION_STATUSES)[number];
+export declare const RAISED_VIA: readonly ["cli", "envelope"];
+export type RaisedVia = (typeof RAISED_VIA)[number];
+export declare const ROUTING_REASONS: readonly ["asked", "escalated", "audience_ended", "reparented", "unanswered_timeout", "cancelled"];
+export type RoutingReason = (typeof ROUTING_REASONS)[number];
+export declare const QUESTION_BODY_STORES: readonly ["company", "personal"];
+export type QuestionBodyStore = (typeof QUESTION_BODY_STORES)[number];
+export declare const LIVENESS_STATES: readonly ["live", "idle", "ended", "lost"];
+export type LivenessState = (typeof LIVENESS_STATES)[number];
+export declare const HISTORY_CAP = 50;
+export declare function isLaneState(value: unknown): value is LaneState;
+export declare function isTerminalLaneState(value: unknown): value is TerminalLaneState;
+export declare function isLaneProvider(value: unknown): value is LaneProvider;
+export declare function isSeniorKind(value: unknown): value is SeniorKind;
+export declare function isHostKind(value: unknown): value is HostKind;
+export declare function isEnvelopeDecision(value: unknown): value is EnvelopeDecision;
+export declare function isQuestionStatus(value: unknown): value is QuestionStatus;
+export declare function isLivenessState(value: unknown): value is LivenessState;
+export declare function parseLaneProvider(value: unknown): LaneProvider;
+export declare function parseLaneState(value: unknown): LaneState;
+export declare function parseQuestionStatus(value: unknown): QuestionStatus;
+export declare function parseLivenessState(value: unknown): LivenessState;
+export declare function parseSeniorKind(value: unknown): SeniorKind;
+export interface LaneCompanyRef {
+    slug: string;
+    uid: string;
+}
+export interface SeniorRef {
+    kind: SeniorKind;
+    /** Required for session and lane; omitted for the user terminal. */
+    id?: string;
+}
+export interface LaneHost {
+    kind: HostKind;
+    id: string;
+}
+export interface SeniorHistoryEntry {
+    from: SeniorRef;
+    to: SeniorRef;
+    at: string;
+    by: string;
+    reason: string;
+}
+export interface AttributionHistoryEntry {
+    project_id: string;
+    story_id: string;
+    message_id: string;
+    at: string;
+}
+export interface LastEnvelopeRef {
+    ref: string;
+    decision: EnvelopeDecision;
+    at: string;
+}
+export interface LaneRecord {
+    schema_version: typeof LANE_SCHEMA_VERSION | string;
+    lane_id: string;
+    /** `null` is a core/personal lane (spec §6.2 / §10). Not an empty slug. */
+    company: LaneCompanyRef | null;
+    project_id: string;
+    story_id: string;
+    thread_id?: string;
+    depth: number;
+    senior: SeniorRef;
+    senior_history: SeniorHistoryEntry[];
+    state: LaneState;
+    queued_reason?: QueuedReason;
+    priority: number;
+    worker?: string;
+    /** Registry-relative directory of the resolved worker, when --worker was set. */
+    worker_path?: string;
+    /** Package name when the worker's realpath is under core/packages. */
+    worker_pack?: string;
+    provider: LaneProvider;
+    account?: string;
+    host: LaneHost;
+    /**
+     * Creating machine's identity when `host.kind` is `outpost` (spec §5.2).
+     * Distinct from `host`, which names where the lane is meant to run.
+     */
+    origin_host?: string;
+    /** How `origin_host` was resolved. Required to compare like-with-like. */
+    origin_host_source?: "imds" | "hostname";
+    version: number;
+    created_at: string;
+    updated_at: string;
+    attribution_history: AttributionHistoryEntry[];
+    last_envelope?: LastEnvelopeRef;
+    /** Effective model id recorded at create/spawn. Omitted when the provider chooses. */
+    model?: string;
+    /** Effective effort level passed to the provider at the last spawn (effort.ts). */
+    effort?: string;
+    /** Where `effort` came from. `cli` pins it across later spawns. */
+    effort_source?: "cli" | "account" | "provider" | "default_rule" | "none";
+    /** Time of the last operator message accepted for this lane. Drives compaction. */
+    last_message_at?: string;
+    /** Last automatic compaction of a resumed session (compaction.ts). */
+    last_compaction?: LaneCompactionRecord;
+    /**
+     * Copied from the last ingested envelope. Omitted when no envelope has
+     * been ingested — absence is not false.
+     */
+    story_complete?: boolean;
+    story_complete_reason?: string;
+    /** Copied from the last ingested envelope when present. */
+    story_status?: StoryStatus;
+    /** Set by the reconcile pass when `--timeout` has passed (spec §5.7). */
+    overdue?: boolean;
+    overdue_at?: string;
+    /** Executing-host heartbeat; stale values mean the host stopped reporting. */
+    last_host_report_at?: string;
+    /**
+     * Set by the watcher when a running worker has made no tool call and
+     * produced no output for the silence window; cleared on the next progress
+     * signal or terminal write. Not a verdict: a long single tool call looks
+     * the same as a hang. See watcher.ts.
+     */
+    stalled?: boolean;
+    stalled_at?: string;
+    stalled_reason?: string;
+    /** Set when the reconcile pass force-admits under the starvation bound. */
+    admitted_reason?: string;
+    terminal_reason?: string;
+    /**
+     * Structured detail behind a named `terminal_reason` (dispatch, pickup and
+     * spawn failures), or the missing-binary search path behind
+     * `provider_binary_missing`. Written by the command and spawn writers.
+     */
+    terminal_details?: Record<string, unknown>;
+    /** SSM command id of the `hq outposts exec` pickup that started this lane. */
+    outpost_command_id?: string;
+    /**
+     * Provider reset time copied from a 429 result. Absent when the text
+     * named none. Distinct from the operator's account enabled switch.
+     */
+    quota_reset_at?: string;
+    /** Set when a 429 refused one model for credits, e.g. "needs credits for claude-fable-5-1". */
+    model_quota_marker?: string;
+    /**
+     * Provider session id parsed from the worker's own stdout when a resumable
+     * provider exits: Claude's JSON `result.session_id`, Codex's
+     * `thread.started.thread_id`. Absent when the provider has none or the
+     * output carried none; `provider_session_id_absent` names why. Never a
+     * guessed or path-derived value.
+     */
+    provider_session_id?: string;
+    provider_session_id_absent?: string;
+    /** Set at spawn when this run continued a recorded session instead of starting fresh. */
+    last_resume?: LaneResumeRecord;
+    /** Cache counters from the last exited run's result. Nothing else from the payload. */
+    last_run_usage?: LaneRunUsage;
+    /**
+     * Spec §4: one repair turn when the final output fails parseLaneEnvelope.
+     * Written by the watcher before the repair spawn, updated on the repair
+     * run's exit. Absent when every envelope this lane wrote parsed first time.
+     */
+    envelope_repair?: LaneEnvelopeRepair;
+    /** Last successful lane_progress mesh delivery, preserved across watcher restarts. */
+    last_progress_event_at?: string;
+}
+/** The v1 fields that must exist on every durable lane record (spec §3). */
+export declare const REQUIRED_LANE_RECORD_FIELDS: readonly ["schema_version", "lane_id", "company", "project_id", "story_id", "depth", "senior", "senior_history", "state", "priority", "provider", "host", "version", "created_at", "updated_at", "attribution_history"];
+export declare const LANE_WRITERS: readonly ["creator", "command", "watcher", "reconcile", "spawn"];
+export type LaneWriter = (typeof LANE_WRITERS)[number];
+/** Field ownership at the durable-record mutation boundary (spec §10.1). */
+export declare const LANE_FIELD_WRITERS: Readonly<Record<keyof LaneRecord, readonly LaneWriter[]>>;
+export interface LaneEnvelopeRepair {
+    /** False when the parse failed but no repair turn could run (see `skipped_reason`). */
+    attempted: boolean;
+    /**
+     * How the repair turn ran: `resume` continues the recorded session (claude,
+     * codex); `fresh_turn` is a new single-turn invocation carrying the raw
+     * output (grok). Absent when no repair ran.
+     */
+    mode?: "resume" | "fresh_turn";
+    succeeded: boolean;
+    first_error: string;
+    /** Parser error from the repair run's output, when that also failed. */
+    second_error?: string;
+    /** Why no repair turn ran: the provider cannot resume, or no session id was recorded. */
+    skipped_reason?: string;
+    /** Envelope slot the repair was asked to rewrite. */
+    envelope_ref?: string;
+    at: string;
+}
+export interface LaneResumeRecord {
+    session_id: string;
+    at: string;
+    trigger: "answered_questions" | "message" | "resume";
+    message_id?: string;
+    /**
+     * `hq lanes resume` only: the state the lane was in when the operator
+     * resumed it (`interrupted`, `done` or `blocked`) and the text they sent.
+     */
+    resumed_from?: "interrupted" | "done" | "blocked";
+    text?: string;
+}
+export interface LaneRunUsage {
+    cache_read_input_tokens: number | null;
+    cache_creation_input_tokens: number | null;
+}
+export interface LaneCompactionRecord {
+    at: string;
+    /** `claude_print_compact`: `claude -p --resume <sid> "/compact"` before the resume. */
+    mechanism: "claude_print_compact";
+    session_id: string;
+    /** `compacted` only when the session transcript gained a compact boundary. */
+    outcome: "compacted" | "no_effect" | "failed";
+    reason?: string;
+    duration_ms: number;
+    /** Milliseconds between the reference time and the resume that compacted. */
+    elapsed_ms: number;
+    /** `last_message_at`, or `created_at` when no message was ever sent. */
+    reference_at: string;
+    /** Context size the provider recorded at the compact boundary. */
+    pre_tokens: number | null;
+    /** Usage of the last run before compaction. */
+    before: LaneRunUsage | null;
+    /** Usage of the first run after compaction, once that run has exited. */
+    after: LaneRunUsage | null;
+    /** `last_resume.at` of the run that followed this compaction. */
+    resume_at?: string;
+}
+export interface QuestionBodyRef {
+    store: QuestionBodyStore;
+    ref: string;
+    digest: string;
+}
+export interface RoutingHistoryEntry {
+    hop: number;
+    audience: SeniorRef;
+    at: string;
+    reason: RoutingReason;
+}
+export interface QuestionAnswer {
+    choice: string;
+    /** Whether the answer selected an offered option or supplied new text. */
+    answer_kind?: "option" | "freeform";
+    notes_ref?: string;
+    answered_by: string;
+    answered_at: string;
+    answered_level: number;
+}
+/**
+ * A question whose options amount to "continue" or "stop" the brief's own
+ * work. The brief already authorises finishing everything it lists, so such a
+ * question is flagged for the operator; nothing answers it automatically.
+ */
+export type QuestionKind = "continue";
+export interface QuestionRecord {
+    schema_version: typeof QUESTION_SCHEMA_VERSION | string;
+    question_id: string;
+    lane_id: string;
+    /** Set by the raiser when the options are only continue/stop. */
+    question_kind?: QuestionKind;
+    /** `null` when the originating lane has no company. */
+    company: LaneCompanyRef | null;
+    project_id: string;
+    story_id: string;
+    thread_id?: string;
+    raised_via: RaisedVia;
+    asked_at: string;
+    origin: {
+        kind: "lane";
+        id: string;
+    };
+    hop: number;
+    status: QuestionStatus;
+    version: number;
+    body: QuestionBodyRef;
+    routing_history: RoutingHistoryEntry[];
+    answer?: QuestionAnswer;
+    /** Merge-on-read preservation of answers retained by conflict sidecars. */
+    answer_history?: QuestionAnswer[];
+}
+export interface EnvelopeQuestion {
+    question: string;
+    context: string;
+    options: string[];
+    recommended?: string;
+}
+export interface LaneEnvelope {
+    schema_version: typeof ENVELOPE_SCHEMA_VERSION;
+    decision: EnvelopeDecision;
+    summary: string;
+    questions?: EnvelopeQuestion[];
+    story_status: StoryStatus;
+    artifacts: unknown[];
+    blocked_reason?: string;
+    story_complete?: boolean;
+    story_complete_reason?: string;
+}
+export interface AccountConfig {
+    home: string;
+    enabled: boolean;
+    disabled_reason?: string;
+    max_running?: number;
+    /** Default model for this account. Beats the provider default; beaten by --model. */
+    model?: string;
+    /** Default effort for this account. Beats the provider default; beaten by --effort. */
+    effort?: string;
+}
+export interface ProviderConfig {
+    max_running: number;
+    max_queued: number;
+    /**
+     * Accepted and ignored for selection. Kept so existing config files parse.
+     * Account pick is least-loaded among enabled, logged-in accounts.
+     */
+    default_account?: string;
+    /** Default model for this provider when the account does not set one. */
+    model?: string;
+    /** Default effort for this provider when the account does not set one. */
+    effort?: string;
+    /**
+     * Resume-time compaction threshold: a resumed session whose last message is
+     * at least this old is compacted first. Absent means the one-hour default.
+     */
+    compact_after_ms?: number;
+    /**
+     * Watcher throttle for `lane_progress` thread events: at most one per this
+     * interval, and only on a tick that saw new tool activity or output. Absent
+     * means the five-minute default.
+     */
+    progress_event_min_interval_ms?: number;
+    accounts: Record<string, AccountConfig>;
+}
+export interface ThrottleConfig {
+    cpu_busy_pause: number;
+    cpu_busy_resume: number;
+    min_available_mem_mb: number;
+}
+/** Session liveness windows from spec §9. Missing keys keep these documented defaults. */
+export interface LivenessWindows {
+    /** Last event within this window (or connected presence) → live. Default 10 minutes. */
+    live_within_ms: number;
+    /** `turn_start` with no later `turn_end` after this window → lost. Default 2 hours. */
+    turn_start_lost_ms: number;
+    /** No event at all for this window (and no `session_end`) → lost. Default 12 hours. */
+    silent_lost_ms: number;
+}
+export interface LanesConfig {
+    schema_version: typeof CONFIG_SCHEMA_VERSION | string;
+    providers: Record<LaneProvider, ProviderConfig>;
+    throttle: ThrottleConfig;
+    liveness: LivenessWindows;
+}
+export declare function parseMajorSchema(schemaVersion: string, expectedPrefix: string, expectedMajor: number): void;
+export declare function parseLaneEnvelope(raw: unknown): LaneEnvelope;
+//# sourceMappingURL=types.d.ts.map