@frockbot/kernel-do 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-do",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-composition": "0.3.0",
-    "@frockbot/kernel-contracts": "0.3.0",
+    "@frockbot/kernel-composition": "0.3.1",
+    "@frockbot/kernel-contracts": "0.3.1",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/authority.ts

@@ -32,6 +32,7 @@ import {
   eventsForFailedRun,
   latestModelRequestJournalState,
   planBotRunRecovery,
+  unresolvedModelRequestFailure,
 } from "./run-recovery.js";
 import {
   BotTurnReconciliationRequiredError,
@@ -283,7 +284,7 @@ export class BotDurableAuthority<Snapshot> {
           previous,
           events,
           modelState.status === "unresolved"
-            ? `Model request "${modelState.request.request.requestId}" has no durable provider outcome`
+            ? unresolvedModelRequestFailure(events, modelState.request)
             : message,
         );
         throw new Error(message);
@@ -366,7 +367,7 @@ export class BotDurableAuthority<Snapshot> {
           previous,
           events,
           modelState.status === "unresolved"
-            ? `Model request "${modelState.request.request.requestId}" has no durable provider outcome`
+            ? unresolvedModelRequestFailure(events, modelState.request)
             : message,
         );
         throw new Error(message);

package/src/run-recovery.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from "bun:test";
+import type { SessionEvent } from "@frockbot/kernel-contracts";
+import {
+  latestModelRequestJournalState,
+  unresolvedModelRequestFailure,
+} from "./run-recovery.js";
+
+// Distributive, so each member of the union keeps its own fields: a bare
+// `Omit` over the union collapses to the keys they all share.
+type UnstampedEvent = SessionEvent extends infer Event
+  ? Event extends SessionEvent
+    ? Omit<Event, "seq" | "timestamp">
+    : never
+  : never;
+
+/** Stamp a journal in order, the way `Session.append` would have. */
+function journal(...events: UnstampedEvent[]): SessionEvent[] {
+  return events.map(
+    (event, index) =>
+      ({
+        ...event,
+        seq: index + 1,
+        timestamp: new Date(Date.UTC(2026, 8, 3, 0, 0, index)).toISOString(),
+      }) as SessionEvent,
+  );
+}
+
+const request: UnstampedEvent = {
+  type: "model/request",
+  turn: 1,
+  step: 1,
+  request: {
+    requestId: "request-1",
+    provider: "flock-ai",
+    model: "@flock/auto",
+    system: "Be concise.",
+    messages: [{ role: "user", content: "hello" }],
+    tools: [],
+  },
+};
+
+function reconciliationRequired(
+  requestId: string,
+  reason: string,
+): UnstampedEvent {
+  return {
+    type: "model/reconciliation-required",
+    turn: 1,
+    step: 1,
+    requestId,
+    reason,
+  };
+}
+
+function unresolved(...events: UnstampedEvent[]): string {
+  const stamped = journal(...events);
+  const state = latestModelRequestJournalState(stamped);
+  if (state.status !== "unresolved") {
+    throw new Error(`expected an unresolved request, got ${state.status}`);
+  }
+  return unresolvedModelRequestFailure(stamped, state.request);
+}
+
+describe("unresolvedModelRequestFailure", () => {
+  test("carries the Agent's journaled reason", () => {
+    expect(
+      unresolved(
+        request,
+        reconciliationRequired(
+          "request-1",
+          "Model response outcome is uncertain: Model response stream ended before a terminal marker",
+        ),
+      ),
+    ).toBe(
+      'Model request "request-1" has no durable provider outcome: Model response outcome is uncertain: Model response stream ended before a terminal marker',
+    );
+  });
+
+  test("reads the last reason when the Turn was retried", () => {
+    expect(
+      unresolved(
+        request,
+        reconciliationRequired("request-1", "first attempt"),
+        reconciliationRequired("request-1", "second attempt"),
+      ),
+    ).toBe(
+      'Model request "request-1" has no durable provider outcome: second attempt',
+    );
+  });
+
+  test("ignores a reason journaled against another request", () => {
+    expect(
+      unresolved(
+        request,
+        reconciliationRequired("request-0", "an earlier call"),
+      ),
+    ).toBe('Model request "request-1" has no durable provider outcome');
+  });
+
+  // A run wedged by isolate eviction never got as far as journaling a reason.
+  test("summarizes when the Agent journaled no reason", () => {
+    expect(unresolved(request)).toBe(
+      'Model request "request-1" has no durable provider outcome',
+    );
+  });
+});

package/src/run-recovery.ts

@@ -61,6 +61,31 @@ export function latestModelRequestJournalState(
   return state;
 }
 
+/**
+ * Why an unresolved Model request parked its run, in the operator's words
+ * where the Agent recorded them.
+ *
+ * The request id alone names *which* call is unsettled but not what went
+ * wrong, and the Agent's own reason is journaled on
+ * `model/reconciliation-required` — an event the chat projection drops. Read
+ * back here it reaches the banner the person is actually looking at.
+ */
+export function unresolvedModelRequestFailure(
+  events: readonly SessionEvent[],
+  request: Extract<SessionEvent, { type: "model/request" }>,
+): string {
+  const requestId = request.request.requestId;
+  const summary = `Model request "${requestId}" has no durable provider outcome`;
+  const journaled = events.findLast(
+    (event) =>
+      event.type === "model/reconciliation-required" &&
+      event.requestId === requestId,
+  );
+  return journaled?.type === "model/reconciliation-required"
+    ? `${summary}: ${journaled.reason}`
+    : summary;
+}
+
 export function planBotRunRecovery<Snapshot>(
   run: StoredRunV1<Snapshot>,
   latest: readonly SessionEvent[],