@h-rig/contracts 0.0.6-alpha.157 → 0.0.6-alpha.158

package/dist/src/run-read-model.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Run read-model capability vocabulary.
+ *
+ * This file defines the contracts-only service seam that run-owner plugins can
+ * provide to CLI, cockpit, supervisor, and doctor surfaces. The OMP session is
+ * the journal source of truth: read-model implementations must key projections
+ * by the canonical run id/session id (`runId === sessionId`). Dispatch handles,
+ * worktree paths, and relay metadata are metadata only, never identity keys.
+ *
+ * Pure: types + one branded id, no folding, defaults, coercion, IO, or provider
+ * implementation.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { RigStatsData } from "./cli-output";
+import type { RunDiscoveryFilter } from "./run-discovery";
+import type { RunJournalProjection } from "./run-journal";
+import type { RunRecord, UnifiedInboxRequest } from "./run-record";
+import type { RunInboxResolutionInit, RunSessionCustomEntry } from "./run-session-journal";
+import type { TaskRecord } from "./task-source";
+export type RunReadModelSource = RunRecord["source"] | "all";
+export type RunReadModelRunSelector = {
+    /** Exact run id/session id, task id, or unique run-id prefix chosen by the caller. */
+    readonly id: string;
+    /** Prefer interpreting `id` as this kind when the caller already knows it. */
+    readonly kind?: "run-id" | "task-id" | "run-id-prefix" | "any";
+};
+export interface RunReadModelListInput {
+    readonly projectRoot: string;
+    readonly taskId?: string | null;
+    readonly source?: RunReadModelSource;
+    readonly includeInactive?: boolean;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelGetInput {
+    readonly projectRoot: string;
+    readonly selector: RunReadModelRunSelector;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelProjectionInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly sessionPath?: string | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelDetailsInput extends RunReadModelGetInput {
+    readonly includeLogs?: boolean;
+    readonly includeSourceTask?: boolean;
+}
+export interface RunReadModelInboxInput {
+    readonly projectRoot: string;
+    readonly kind?: "approval" | "input" | "all";
+    readonly runId?: string | null;
+    readonly taskId?: string | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelStatsInput {
+    readonly projectRoot: string;
+    /** ISO timestamp lower bound, or null for all-time. */
+    readonly since?: string | null;
+    /** Optional caller-supplied records, used when the surface already listed runs. */
+    readonly runs?: readonly RunRecord[];
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelInspectRowsInput {
+    readonly projectRoot: string;
+    readonly runs?: readonly RunRecord[];
+    readonly pendingInbox?: number | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelControlTargetInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly taskId?: string | null;
+    readonly purpose?: "attach" | "steer" | "stop" | "pause" | "resume" | "resolve-inbox";
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export type RunReadModelControl = {
+    readonly kind: "steer";
+    readonly message: string;
+} | {
+    readonly kind: "stop";
+    readonly reason: string;
+} | {
+    readonly kind: "pause";
+} | {
+    readonly kind: "resume";
+};
+export interface RunReadModelControlInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly control: RunReadModelControl;
+    readonly requestedBy?: string | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelControlResult {
+    readonly runId: string;
+    readonly kind: RunReadModelControl["kind"];
+    readonly status: "delivered" | "not-found" | "not-live" | "unsupported";
+    readonly delivered: boolean;
+    readonly detail?: string | null;
+}
+export interface RunReadModelInboxResolutionInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly resolution: RunInboxResolutionInit;
+    readonly requestedBy?: string | null;
+    readonly discoveryFilter?: RunDiscoveryFilter;
+}
+export interface RunReadModelRemoveRegistryEntryInput {
+    readonly projectRoot: string;
+    /** Canonical run id/session id. */
+    readonly runId: string;
+}
+export interface RunReadModelRemoveRegistryEntryResult {
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly removed: boolean;
+}
+export interface RunReadModelInboxCounts {
+    readonly approvals: number;
+    readonly inputs: number;
+    readonly total: number;
+}
+export interface RunReadModelInboxRecord {
+    readonly runId: string;
+    readonly taskId: string | null;
+    readonly requestId: string;
+    readonly kind: "approval" | "input";
+    readonly status: "pending";
+    readonly title: string;
+    readonly body?: string | null;
+    readonly prompt: string;
+    readonly requestedAt: string | null;
+    readonly payload: unknown;
+    readonly source: "run";
+}
+export interface RunReadModelInboxResolutionResult {
+    readonly runId: string;
+    readonly requestId: string;
+    readonly kind: "approval" | "input";
+    readonly status: "resolved" | "not-found" | "not-live" | "unsupported";
+    readonly delivered: boolean;
+    readonly detail?: string | null;
+}
+export interface RunReadModelControlTarget {
+    /** Canonical run id/session id. */
+    readonly runId: string;
+    readonly taskId: string | null;
+    readonly sessionId: string | null;
+    readonly sessionPath: string | null;
+    readonly joinLink: string | null;
+    readonly webLink: string | null;
+    readonly relayUrl: string | null;
+    readonly collabCwd: string | null;
+    readonly live: boolean;
+    readonly stale: boolean;
+    readonly canDeliver: boolean;
+    readonly reason?: string | null;
+}
+export type RunReadModelStats = RigStatsData;
+export type RunReadModelStatusPhase = "starting" | "active" | "waiting" | "paused" | "needs-attention" | "completed" | "failed" | "stopped" | "unknown";
+export type RunReadModelStatusRole = "success" | "action-yellow" | "active-cyan" | "failure" | "muted" | "neutral";
+export interface RunReadModelRunClassification {
+    readonly status: string;
+    readonly phase: RunReadModelStatusPhase;
+    readonly role: RunReadModelStatusRole;
+    readonly rank: number;
+    readonly isActive: boolean;
+    readonly isTerminal: boolean;
+    readonly isNeedsAttention: boolean;
+}
+export interface RunReadModelInspectRow {
+    readonly id: string;
+    readonly label: string;
+    readonly currentValue: string;
+    readonly values?: readonly string[];
+    readonly heading?: boolean;
+    readonly description?: string;
+}
+export interface RunReadModelFailureSummary {
+    readonly kind: string;
+    readonly summary: string;
+    readonly detail?: string | null;
+    readonly retryable?: boolean | null;
+}
+export interface RunReadModelDetails {
+    readonly run: RunRecord;
+    readonly projection: RunJournalProjection;
+    readonly pendingInbox: readonly UnifiedInboxRequest[];
+    readonly inboxCounts: RunReadModelInboxCounts;
+    readonly sourceTask?: TaskRecord | null;
+    readonly sessionEntries?: readonly RunSessionCustomEntry[];
+    readonly failures: readonly RunReadModelFailureSummary[];
+    readonly logs: readonly string[];
+}
+export interface RunReadModelInspectResult {
+    readonly details: RunReadModelDetails;
+    readonly classification: RunReadModelRunClassification;
+    readonly rows: readonly RunReadModelInspectRow[];
+}
+/**
+ * Multi-method run read-model service capability.
+ *
+ * Providers own the executable discovery/folding/classification/control-target
+ * lookup. Consumers depend only on this contracts vocabulary and resolve the
+ * provider through the typed capability seam.
+ */
+export interface RunReadModelService {
+    readonly listRuns: (input: RunReadModelListInput) => Promise<readonly RunRecord[]>;
+    readonly getRun: (input: RunReadModelGetInput) => Promise<RunRecord | null>;
+    readonly getRunProjection: (input: RunReadModelProjectionInput) => Promise<RunJournalProjection | null>;
+    readonly getRunDetails: (input: RunReadModelDetailsInput) => Promise<RunReadModelDetails | null>;
+    readonly inspectRun: (input: RunReadModelDetailsInput) => Promise<RunReadModelInspectResult | null>;
+    readonly listInboxRecords: (input: RunReadModelInboxInput) => Promise<readonly RunReadModelInboxRecord[]>;
+    readonly getInboxCounts: (input: RunReadModelInboxInput) => Promise<RunReadModelInboxCounts>;
+    readonly resolveInboxRequest: (input: RunReadModelInboxResolutionInput) => Promise<RunReadModelInboxResolutionResult>;
+    readonly getStats: (input: RunReadModelStatsInput) => Promise<RunReadModelStats>;
+    readonly getInspectRows: (input: RunReadModelInspectRowsInput) => Promise<readonly RunReadModelInspectRow[]>;
+    readonly deliverControl: (input: RunReadModelControlInput) => Promise<RunReadModelControlResult>;
+    readonly classifyRun: (run: RunRecord) => RunReadModelRunClassification;
+    readonly resolveControlTarget: (input: RunReadModelControlTargetInput) => Promise<RunReadModelControlTarget | null>;
+    readonly removeRunRegistryEntry: (input: RunReadModelRemoveRegistryEntryInput) => Promise<RunReadModelRemoveRegistryEntryResult>;
+}
+/** Stable id string for the run read-model service capability. */
+export declare const RUN_READ_MODEL_CAPABILITY_ID = "rig.runs.read-model";
+/**
+ * Branded run read-model capability id. `defineCapability(RUN_READ_MODEL)`
+ * (provider and consumers independently) resolves to a `RunReadModelService`.
+ */
+export declare const RUN_READ_MODEL: CapabilityId<RunReadModelService>;

package/dist/src/run-read-model.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/run-read-model.ts
+var RUN_READ_MODEL_CAPABILITY_ID = "rig.runs.read-model";
+var RUN_READ_MODEL = makeCapabilityId(RUN_READ_MODEL_CAPABILITY_ID);
+export {
+  RUN_READ_MODEL_CAPABILITY_ID,
+  RUN_READ_MODEL
+};

package/dist/src/run-record.d.ts

@@ -43,14 +43,3 @@ export interface RunRecord {
     /** The full folded journal (empty projection when no journal was readable). */
     readonly projection: RunJournalProjection;
 }
-/**
- * Index runs by their task id, keeping only the most-recently-updated run per
- * task. Pure run primitive relocated out of the dissolved @rig/client facade
- * (the META vocabulary floor is the correct home for a typed, policy-free run
- * coercion that multiple plugins build projections on).
- */
-export declare function latestRunByTaskId<T extends {
-    readonly taskId: string | null;
-    readonly updatedAt: string | null;
-    readonly startedAt: string | null;
-}>(runs: readonly T[]): Map<string, T>;

package/dist/src/run-record.js

@@ -1,17 +1 @@
 // @bun
-// packages/contracts/src/run-record.ts
-function latestRunByTaskId(runs) {
-  const byTask = new Map;
-  const stamp = (run) => Date.parse(run.updatedAt ?? run.startedAt ?? "") || 0;
-  for (const run of runs) {
-    if (!run.taskId)
-      continue;
-    const current = byTask.get(run.taskId);
-    if (!current || stamp(run) >= stamp(current))
-      byTask.set(run.taskId, run);
-  }
-  return byTask;
-}
-export {
-  latestRunByTaskId
-};

package/dist/src/run-registry-backbone.d.ts

@@ -0,0 +1,56 @@
+import type { CapabilityId } from "./capability-id";
+import type { RigWorkflowOwner } from "./workflow-journal";
+import type { RunRecord } from "./run-record";
+import type { RunStatus } from "./runtime";
+/**
+ * cap:run-registry-backbone — transport-owned relay/registry room publication.
+ *
+ * The transport plugin owns the concrete @rig/relay-registry client. Run workers
+ * publish journal-derived projections through this structural seam so the worker
+ * lifecycle engine does not import the relay-registry implementation package.
+ */
+export declare const RUN_REGISTRY_BACKBONE_CAPABILITY_ID = "transport.run-registry-backbone";
+export type RunRegistryOwner = RigWorkflowOwner;
+export type RunRegistryStatus = RunStatus | "starting" | "waiting-input";
+export type RunRegistryRunProjection = Pick<RunRecord, "runId" | "taskId" | "title" | "status" | "source" | "startedAt" | "updatedAt" | "completedAt" | "joinLink" | "webLink" | "relayUrl" | "sessionPath" | "prUrl" | "worktreePath" | "pendingApprovals" | "pendingInputs" | "steeringCount" | "stallCount" | "errorSummary" | "timeline" | "collabCwd"> & {
+    readonly cwd?: string | null;
+    readonly dispatchHandle?: string | null;
+};
+export interface RunRegistryRegisterRoomInput {
+    readonly roomId: string;
+    readonly owner: RunRegistryOwner;
+    readonly repo: string;
+    readonly title: string;
+    readonly status: RunRegistryStatus;
+    readonly joinLink: string;
+    readonly webLink: string;
+    readonly relayUrl: string;
+    readonly startedAt: string;
+    readonly cwd?: string;
+    readonly sessionPath?: string;
+    readonly pid?: number;
+    readonly projection?: RunRegistryRunProjection;
+}
+export interface RunRegistryClient {
+    readonly registerRoom: (room: RunRegistryRegisterRoomInput) => Promise<unknown>;
+    readonly heartbeatRoom: (roomId: string, status: RunRegistryStatus, projection?: RunRegistryRunProjection) => Promise<unknown>;
+    readonly removeRoom: (roomId: string) => Promise<boolean>;
+}
+export interface RunWorkerProjectionConnection {
+    readonly ready: Promise<void>;
+    push(projection: RunRegistryRunProjection): void;
+    close(): void;
+}
+export interface RunRegistryBackboneService {
+    readonly createRegistryClient: (options: {
+        readonly baseUrl: string;
+        readonly namespaceKey: string;
+    }) => RunRegistryClient;
+    readonly connectWorkerProjection: (options: {
+        readonly baseUrl: string;
+        readonly namespaceKey: string;
+        readonly runId: string;
+    }) => RunWorkerProjectionConnection;
+    readonly coerceRegistryStatus: (value: unknown, fallback: RunRegistryStatus) => RunRegistryStatus;
+}
+export declare const RUN_REGISTRY_BACKBONE: CapabilityId<RunRegistryBackboneService>;

package/dist/src/run-registry-backbone.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/run-registry-backbone.ts
+var RUN_REGISTRY_BACKBONE_CAPABILITY_ID = "transport.run-registry-backbone";
+var RUN_REGISTRY_BACKBONE = makeCapabilityId(RUN_REGISTRY_BACKBONE_CAPABILITY_ID);
+export {
+  RUN_REGISTRY_BACKBONE_CAPABILITY_ID,
+  RUN_REGISTRY_BACKBONE
+};

package/dist/src/run-session-journal.d.ts

@@ -1,4 +1,4 @@
-import { type RunJournalEvent, type RunJournalProjection } from "./run-journal";
+import { type RunJournalEvent } from "./run-journal";
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 export type RunJournalEventInit = DistributiveOmit<RunJournalEvent, "v" | "seq" | "at" | "runId">;
 export declare const RIG_RUN_STATUS_CHANGED = "rig.run.status-changed";
@@ -17,21 +17,9 @@ export declare const RIG_RUN_PIPELINE_RESOLVED = "rig.run.pipeline-resolved";
 export declare const RIG_RUN_STAGE_OUTCOME = "rig.run.stage-outcome";
 export declare const RIG_STOP_SENTINEL = "<<RIG_STOP";
 export declare const RIG_STOP_SENTINEL_END = ">>";
-export declare function buildStopSentinel(runId: string, reason?: string | null, requestedBy?: string): string;
-export declare function parseStopSentinel(text: string, expectedRunId: string): {
-    reason: string | null;
-} | null;
 export declare const RIG_PAUSE_SENTINEL = "<<RIG_PAUSE";
 export declare const RIG_RESUME_SENTINEL = "<<RIG_RESUME";
 export declare const RIG_CONTROL_SENTINEL_END = ">>";
-export declare function buildPauseSentinel(runId: string, requestedBy?: string): string;
-export declare function parsePauseSentinel(text: string, expectedRunId: string): {
-    requestedBy: string | null;
-} | null;
-export declare function buildResumeSentinel(runId: string, requestedBy?: string): string;
-export declare function parseResumeSentinel(text: string, expectedRunId: string): {
-    requestedBy: string | null;
-} | null;
 export type RunInboxResolutionSentinel = {
     kind: "approval";
     requestId: string;
@@ -55,16 +43,6 @@ export type RunInboxResolutionInit = {
     requestId: string;
     answers: Record<string, string>;
 };
-export declare function buildInboxResolutionSentinel(runId: string, resolution: RunInboxResolutionInit, requestedBy?: string): string;
-export declare function parseInboxResolutionSentinel(text: string, expectedRunId: string): RunInboxResolutionSentinel | null;
-/**
- * The OMP session id embedded in a session journal filename
- * (`<ISO-timestamp>_<sessionId>.jsonl`). This is a run's CANONICAL id — the same
- * id OMP hosts as the collab roomId and the relay registry + operator CLI key on.
- * A run's dispatch/worktree id is different; this is what links them, so stop /
- * steer / discovery all resolve a run by one id (the OMP session id).
- */
-export declare function sessionIdFromSessionFile(sessionPath: string | null | undefined): string | null;
 export declare const CUSTOM_TYPE_FOR: {
     readonly "status-changed": "rig.run.status-changed";
     readonly "record-patch": "rig.run.record-patch";
@@ -88,6 +66,4 @@ export type RunSessionCustomEntry = {
     customType?: string;
     data?: unknown;
 };
-export declare function isRunSessionCustomType(customType: string | undefined): customType is RunSessionCustomType;
-export declare function foldRunSessionEntries(entries: ReadonlyArray<RunSessionCustomEntry>, runId: string): RunJournalProjection;
 export {};