@h-rig/contracts 0.0.6-alpha.103 → 0.0.6-alpha.119

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

@@ -0,0 +1,45 @@
+import type { RunJournalProjection } from "./run-journal";
+import type { RigRunTimelineEntry } from "./run-timeline";
+export type UnifiedInboxRequest = {
+    readonly requestId: string;
+    readonly kind: "approval" | "input";
+    readonly title: string;
+    readonly body?: string | null;
+    readonly options?: readonly string[];
+    readonly requestedAt: string | null;
+    readonly source: "run";
+};
+/** Unified operator-facing run record shared by CLI, cockpit, relay, and client projection logic. */
+export interface RunRecord {
+    readonly runId: string;
+    readonly taskId: string | null;
+    readonly title: string;
+    /** RunStatus from the folded journal, or a liveness-derived fallback. */
+    readonly status: string;
+    readonly source: "local" | "remote";
+    /** True when the run is currently discoverable (registry heartbeat or local host). */
+    readonly live: boolean;
+    readonly stale: boolean;
+    readonly startedAt: string | null;
+    readonly updatedAt: string | null;
+    readonly completedAt: string | null;
+    readonly joinLink: string | null;
+    readonly webLink: string | null;
+    readonly relayUrl: string | null;
+    readonly sessionPath: string | null;
+    readonly prUrl: string | null;
+    readonly worktreePath: string | null;
+    readonly pendingApprovals: number;
+    readonly pendingInputs: number;
+    readonly steeringCount: number;
+    readonly stallCount: number;
+    readonly errorSummary?: string | null;
+    /** Timeline entries folded from the same OMP session custom entries as the journal. */
+    readonly timeline: RigRunTimelineEntry[];
+    /** Pending rig.run.* approvals/inputs only; rig.workflow.inbox.* is intentionally dead. */
+    readonly inbox: UnifiedInboxRequest[];
+    /** Live collab cwd when present in registry/discovery. */
+    readonly collabCwd: string | null;
+    /** The full folded journal (empty projection when no journal was readable). */
+    readonly projection: RunJournalProjection;
+}

package/dist/src/run-record.js

@@ -0,0 +1 @@
+// @bun

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

@@ -19,6 +19,42 @@ export declare function buildStopSentinel(runId: string, reason?: string | null,
 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;
+    decision: "approve" | "reject";
+    note?: string | null;
+    requestedBy: string | null;
+} | {
+    kind: "input";
+    requestId: string;
+    answers: Record<string, string>;
+    requestedBy: string | null;
+};
+export declare const RIG_INBOX_RESOLUTION_SENTINEL = "<<RIG_INBOX_RESOLUTION";
+export type RunInboxResolutionInit = {
+    kind: "approval";
+    requestId: string;
+    decision: "approve" | "reject";
+    note?: string | null;
+} | {
+    kind: "input";
+    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

package/dist/src/run-session-journal.js

@@ -1499,6 +1499,85 @@ function parseStopSentinel(text, expectedRunId) {
   const reason = body.match(/(?:^|\s)reason=(.+)$/)?.[1]?.trim() ?? null;
   return { reason };
 }
+var RIG_PAUSE_SENTINEL = "<<RIG_PAUSE";
+var RIG_RESUME_SENTINEL = "<<RIG_RESUME";
+var RIG_CONTROL_SENTINEL_END = ">>";
+function buildControlSentinel(marker, runId, requestedBy) {
+  return `${marker} runId=${runId} requestedBy=${requestedBy}${RIG_CONTROL_SENTINEL_END}`;
+}
+function parseControlSentinel(marker, text, expectedRunId) {
+  const start = text.indexOf(marker);
+  if (start < 0)
+    return null;
+  const end = text.indexOf(RIG_CONTROL_SENTINEL_END, start);
+  const body = text.slice(start + marker.length, end >= 0 ? end : undefined).trim();
+  const runId = body.match(/(?:^|\s)runId=([^\s>]+)/)?.[1] ?? "";
+  if (runId && runId !== expectedRunId)
+    return null;
+  const requestedBy = body.match(/(?:^|\s)requestedBy=([^\s>]+)/)?.[1] ?? null;
+  return { requestedBy };
+}
+function buildPauseSentinel(runId, requestedBy = "rig") {
+  return buildControlSentinel(RIG_PAUSE_SENTINEL, runId, requestedBy);
+}
+function parsePauseSentinel(text, expectedRunId) {
+  return parseControlSentinel(RIG_PAUSE_SENTINEL, text, expectedRunId);
+}
+function buildResumeSentinel(runId, requestedBy = "rig") {
+  return buildControlSentinel(RIG_RESUME_SENTINEL, runId, requestedBy);
+}
+function parseResumeSentinel(text, expectedRunId) {
+  return parseControlSentinel(RIG_RESUME_SENTINEL, text, expectedRunId);
+}
+var RIG_INBOX_RESOLUTION_SENTINEL = "<<RIG_INBOX_RESOLUTION";
+function encodeInboxResolutionPayload(payload) {
+  return encodeURIComponent(JSON.stringify(payload));
+}
+function decodeInboxResolutionPayload(payload) {
+  try {
+    const parsed = JSON.parse(decodeURIComponent(payload));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return null;
+    const record = parsed;
+    if (record.kind === "approval") {
+      const requestId = typeof record.requestId === "string" ? record.requestId.trim() : "";
+      const decision = record.decision === "approve" || record.decision === "reject" ? record.decision : null;
+      const note = typeof record.note === "string" ? record.note : record.note === null ? null : undefined;
+      if (!requestId || !decision)
+        return null;
+      return { kind: "approval", requestId, decision, ...note !== undefined ? { note } : {} };
+    }
+    if (record.kind === "input") {
+      const requestId = typeof record.requestId === "string" ? record.requestId.trim() : "";
+      const answers = record.answers && typeof record.answers === "object" && !Array.isArray(record.answers) ? Object.fromEntries(Object.entries(record.answers).filter((entry) => typeof entry[1] === "string")) : null;
+      if (!requestId || !answers)
+        return null;
+      return { kind: "input", requestId, answers };
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+function buildInboxResolutionSentinel(runId, resolution, requestedBy = "rig") {
+  return `${RIG_INBOX_RESOLUTION_SENTINEL} runId=${runId} requestedBy=${requestedBy} data=${encodeInboxResolutionPayload(resolution)}${RIG_CONTROL_SENTINEL_END}`;
+}
+function parseInboxResolutionSentinel(text, expectedRunId) {
+  const start = text.indexOf(RIG_INBOX_RESOLUTION_SENTINEL);
+  if (start < 0)
+    return null;
+  const end = text.indexOf(RIG_CONTROL_SENTINEL_END, start);
+  const body = text.slice(start + RIG_INBOX_RESOLUTION_SENTINEL.length, end >= 0 ? end : undefined).trim();
+  const runId = body.match(/(?:^|\s)runId=([^\s>]+)/)?.[1] ?? "";
+  if (runId && runId !== expectedRunId)
+    return null;
+  const requestedBy = body.match(/(?:^|\s)requestedBy=([^\s>]+)/)?.[1] ?? null;
+  const payload = body.match(/(?:^|\s)data=([^\s>]+)/)?.[1] ?? "";
+  const decoded = decodeInboxResolutionPayload(payload);
+  if (!decoded)
+    return null;
+  return { ...decoded, requestedBy };
+}
 function sessionIdFromSessionFile(sessionPath) {
   if (!sessionPath)
     return null;
@@ -1560,9 +1639,15 @@ function foldRunSessionEntries(entries, runId) {
 export {
   sessionIdFromSessionFile,
   parseStopSentinel,
+  parseResumeSentinel,
+  parsePauseSentinel,
+  parseInboxResolutionSentinel,
   isRunSessionCustomType,
   foldRunSessionEntries,
   buildStopSentinel,
+  buildResumeSentinel,
+  buildPauseSentinel,
+  buildInboxResolutionSentinel,
   TYPE_FOR_CUSTOM,
   RIG_STOP_SENTINEL_END,
   RIG_STOP_SENTINEL,
@@ -1578,5 +1663,9 @@ export {
   RIG_RUN_APPROVAL_RESOLVED,
   RIG_RUN_APPROVAL_REQUESTED,
   RIG_RUN_ADOPTED,
+  RIG_RESUME_SENTINEL,
+  RIG_PAUSE_SENTINEL,
+  RIG_INBOX_RESOLUTION_SENTINEL,
+  RIG_CONTROL_SENTINEL_END,
   CUSTOM_TYPE_FOR
 };

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

@@ -0,0 +1,9 @@
+import { type RunSessionCustomEntry } from "./run-session-journal";
+export type RigRunTimelineEntry = {
+    at: string | null;
+    type: string;
+    stage?: string | null;
+    status?: string | null;
+    detail?: string | null;
+};
+export declare function timelineEntriesFromCustomEntries(entries: readonly RunSessionCustomEntry[]): readonly RigRunTimelineEntry[];