@frockbot/kernel-do 0.3.29 → 0.3.31

package/package.json

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

package/src/authority.ts

@@ -31,6 +31,7 @@ import {
   completeStoredRun,
   type TerminalPackageRecords,
   type SupersededPackageRecords,
+  type FailedRunNotification,
   failStoredRun,
   requireStoredRunReconciliation,
 } from "./run-terminal.js";
@@ -134,6 +135,24 @@ export interface BotDurableAuthorityHooks<Snapshot> {
     snapshot: Snapshot,
     result: BotTurnCompletion,
   ): BotNotificationIntent | undefined;
+  /**
+   * Notification policy for a Turn that ended `failed`, given the settings the
+   * Turn was admitted under and its settled record. `undefined` records none.
+   *
+   * The snapshot comes off the run itself rather than from a fresh read: a
+   * failure settles on paths — recovery after a restart, the stale-run repair —
+   * where nothing else has the settings to hand, and `configurationSnapshot` is
+   * the durable copy of exactly the ones this Turn ran under.
+   */
+  failureNotification?(
+    snapshot: Snapshot,
+    failed: {
+      runId: string;
+      /** The stored diagnostic. Never shown to a person as it stands. */
+      failure: string;
+      events: readonly SessionEvent[];
+    },
+  ): BotNotificationIntent | undefined;
   /**
    * Package records written in the same transaction that settles a Turn, given
    * the settled run and the admission-index cursor it was admitted under. The
@@ -1349,6 +1368,7 @@ export class BotDurableAuthority<Snapshot> {
         run.events,
         STALE_RUNNING_RUN_FAILURE_V1,
         this.supersededPackageRecords(),
+        this.failedRunNotification(),
       );
       await this.refreshRecoveryAlarm(transaction);
     });
@@ -1823,6 +1843,21 @@ export class BotDurableAuthority<Snapshot> {
   }
 
   /** The Package's superseded-record hook, or `undefined` when it has none. */
+  /**
+   * The Package's failed-Turn notification hook, bound to the run's own
+   * durable snapshot. Absent when the Package contributes none.
+   */
+  private failedRunNotification(): FailedRunNotification<Snapshot> | undefined {
+    const hook = this.hooks.failureNotification;
+    if (!hook) return undefined;
+    return (run) =>
+      hook.call(this.hooks, run.configurationSnapshot, {
+        runId: run.runId,
+        failure: run.failure ?? "",
+        events: run.events,
+      });
+  }
+
   private supersededPackageRecords():
     SupersededPackageRecords<Snapshot> | undefined {
     const hook = this.hooks.supersededRecords;
@@ -1890,6 +1925,7 @@ export class BotDurableAuthority<Snapshot> {
         events,
         boundedRunFailureV1(failure),
         this.supersededPackageRecords(),
+        this.failedRunNotification(),
       );
       await this.refreshRecoveryAlarm(transaction);
     });
@@ -2108,6 +2144,7 @@ export class BotDurableAuthority<Snapshot> {
           events,
           plan.failure,
           this.supersededPackageRecords(),
+          this.failedRunNotification(),
         );
         await this.refreshRecoveryAlarm(transaction);
         return undefined;

package/src/run-terminal-failure-notification.test.ts

@@ -0,0 +1,227 @@
+// A Turn that ends `failed` owes the person who was waiting on it the same
+// kind of notice a completed one gives them. Before this, only a completed
+// Turn recorded a notification intent, so a deadline, a provider outage or a
+// restart reached nobody who was not still looking at that conversation.
+import { describe, expect, test } from "bun:test";
+import { Session, type SessionEvent } from "@frockbot/kernel-contracts";
+import { MemoryStorage } from "./memory-storage.fixture.ts";
+import { createStoredRunCodecV1, type StoredRunV1 } from "./run-records.ts";
+import { failStoredRun } from "./run-terminal.ts";
+
+interface Snapshot {
+  name: string;
+  notify: boolean;
+}
+
+const codec = createStoredRunCodecV1<Snapshot>({
+  decodeRunId: (value) => String(value),
+  decodeConfigurationSnapshot: (value) => value as Snapshot,
+});
+
+const SESSION_ID = "user-1:primary";
+
+const KEYS = {
+  run: "run:run-1",
+  activeRun: "active-run",
+  latestEvents: "latest-events",
+  notificationPrefix: "notification:",
+};
+
+/** The Package policy under test: it reads the run's own durable snapshot. */
+function failureNotification(run: StoredRunV1<Snapshot>) {
+  if (!run.configurationSnapshot.notify) return undefined;
+  return {
+    notificationId: `run-failed-${run.runId}`,
+    runId: run.runId,
+    createdAt: "2026-09-05T00:00:00.000Z",
+    title: `${run.configurationSnapshot.name} couldn't finish`,
+    body: "This Bot couldn't finish its reply. Try again.",
+  };
+}
+
+function journal(): SessionEvent[] {
+  const events: SessionEvent[] = [];
+  const session = new Session(SESSION_ID, (envelope) => {
+    events.push(envelope.event);
+  });
+  session.appendBatch([
+    { type: "turn/start", turn: 1 },
+    { type: "step/start", turn: 1, step: 1 },
+    {
+      type: "user/message",
+      turn: 1,
+      step: 1,
+      messageId: "message-1",
+      text: "hello",
+    },
+  ]);
+  return events;
+}
+
+function storedRun(
+  events: SessionEvent[],
+  intent: Partial<StoredRunV1<Snapshot>>,
+): StoredRunV1<Snapshot> {
+  return {
+    runId: "run-1",
+    commandFingerprint: "fingerprint-1",
+    sessionId: SESSION_ID,
+    acceptedAt: "2026-09-05T00:00:00.000Z",
+    input: "hello",
+    events,
+    effectAdmissions: [],
+    status: "running",
+    phase: "executing",
+    compositionGenerationId: "generation-1",
+    configurationSnapshot: { name: "Bob", notify: true },
+    previousEventCount: 0,
+    ...intent,
+  };
+}
+
+async function settledStorage(
+  intent: Partial<StoredRunV1<Snapshot>> = {},
+): Promise<{ storage: MemoryStorage; events: SessionEvent[] }> {
+  const storage = new MemoryStorage();
+  const events = journal();
+  await storage.put({
+    [KEYS.activeRun]: "run-1",
+    [KEYS.run]: storedRun(events, intent),
+    [KEYS.latestEvents]: events,
+  });
+  return { storage, events };
+}
+
+function notifications(storage: MemoryStorage): unknown[] {
+  return [...storage.values.entries()]
+    .filter(([key]) => key.startsWith(KEYS.notificationPrefix))
+    .map(([, value]) => value);
+}
+
+describe("the notification a failed Turn records", () => {
+  test("is composed from the snapshot the Turn was admitted under", async () => {
+    const { storage, events } = await settledStorage();
+
+    await failStoredRun(
+      codec,
+      storage,
+      KEYS,
+      "run-1",
+      [],
+      events,
+      "Bot turn ended with outcome model-error: Model request failed (401)",
+      undefined,
+      failureNotification,
+    );
+
+    expect(notifications(storage)).toEqual([
+      {
+        notificationId: "run-failed-run-1",
+        runId: "run-1",
+        createdAt: "2026-09-05T00:00:00.000Z",
+        title: "Bob couldn't finish",
+        body: "This Bot couldn't finish its reply. Try again.",
+      },
+    ]);
+  });
+
+  test("is not recorded when the Bot's own policy declines it", async () => {
+    const { storage, events } = await settledStorage({
+      configurationSnapshot: { name: "Bob", notify: false },
+    });
+
+    await failStoredRun(
+      codec,
+      storage,
+      KEYS,
+      "run-1",
+      [],
+      events,
+      "Bot turn ended with outcome model-error",
+      undefined,
+      failureNotification,
+    );
+
+    expect(notifications(storage)).toEqual([]);
+  });
+
+  test("is written once, however often the run is settled again", async () => {
+    const { storage, events } = await settledStorage();
+
+    await failStoredRun(
+      codec,
+      storage,
+      KEYS,
+      "run-1",
+      [],
+      events,
+      "the service restarted",
+      undefined,
+      failureNotification,
+    );
+    // What acknowledging it does. A recovery pass over the same run must not
+    // bring it back — the person has already read it.
+    storage.values.delete(`${KEYS.notificationPrefix}run-failed-run-1`);
+
+    await failStoredRun(
+      codec,
+      storage,
+      KEYS,
+      "run-1",
+      [],
+      events,
+      "the service restarted",
+      undefined,
+      failureNotification,
+    );
+
+    expect(notifications(storage)).toEqual([]);
+  });
+
+  test("is not recorded for a Turn a later message replaced", async () => {
+    const { storage, events } = await settledStorage({
+      supersededAt: "2026-09-05T00:01:00.000Z",
+      supersededBy: "run-2",
+    });
+
+    await failStoredRun(
+      codec,
+      storage,
+      KEYS,
+      "run-1",
+      [],
+      events,
+      "Bot turn ended with outcome model-error",
+      undefined,
+      failureNotification,
+    );
+
+    expect((storage.values.get(KEYS.run) as StoredRunV1<Snapshot>).status).toBe(
+      "superseded",
+    );
+    expect(notifications(storage)).toEqual([]);
+  });
+
+  test("is not recorded for a Turn the person stopped", async () => {
+    const { storage, events } = await settledStorage({
+      stopRequestedAt: "2026-09-05T00:01:00.000Z",
+    });
+
+    await failStoredRun(
+      codec,
+      storage,
+      KEYS,
+      "run-1",
+      [],
+      events,
+      "Bot turn ended with outcome model-error",
+      undefined,
+      failureNotification,
+    );
+
+    expect((storage.values.get(KEYS.run) as StoredRunV1<Snapshot>).status).toBe(
+      "cancelled",
+    );
+    expect(notifications(storage)).toEqual([]);
+  });
+});

package/src/run-terminal.ts

@@ -4,6 +4,7 @@ import {
   type SessionEvent,
 } from "@frockbot/kernel-contracts";
 import type {
+  BotNotificationIntent,
   BotTurnCompletion,
   StoredRunCodecV1,
   StoredRunV1,
@@ -132,6 +133,26 @@ export type SupersededPackageRecords<Snapshot> = (input: {
   read<T>(key: string): Promise<T | undefined>;
 }) => Promise<Record<string, unknown>>;
 
+/**
+ * The notification a Turn that ended `failed` owes the person who was waiting
+ * on it, decided by the Package that owns notification content.
+ *
+ * A completed Turn already tells them — "Bob replied", with what it said —
+ * through the completion's own intent. A failed Turn had none, so the only
+ * person who ever learned was the one still looking at that conversation. This
+ * is the same seam for the other outcome: the kernel hands over the settled
+ * record, whose `configurationSnapshot` is the durable copy of the settings
+ * the Turn was admitted under, and writes back whatever intent comes out
+ * without reading it.
+ *
+ * It is consulted only on the transition into `failed`, so a replay or a
+ * recovery pass over a run that already settled writes nothing — an
+ * acknowledged notification stays acknowledged.
+ */
+export type FailedRunNotification<Snapshot> = (
+  run: StoredRunV1<Snapshot>,
+) => BotNotificationIntent | undefined;
+
 /**
  * Settles a superseded run as terminal `superseded` and clears its active
  * marker. Like a cancelled run it produces no response text, no failure, and
@@ -325,12 +346,17 @@ export async function failStoredRun<Snapshot>(
   events: readonly SessionEvent[],
   failure: string,
   supersededRecords?: SupersededPackageRecords<Snapshot>,
+  failureNotification?: FailedRunNotification<Snapshot>,
 ): Promise<
   "failed" | "cancelled" | "superseded" | "preserved-completion" | "missing"
 > {
   const run = await hydratedRun(codec, storage, keys.run);
   if (!run) return "missing";
   if (run.status === "completed") return "preserved-completion";
+  // Whether this settlement is the one that fails the run. A run already
+  // `failed` can be settled again — recovery and the stale-run repair both
+  // re-enter — and the second pass owes nobody a second notification.
+  const alreadyFailed = run.status === "failed";
   // A stopped run never becomes `failed`: Stop is the durable outcome.
   if (run.stopRequestedAt) {
     return cancelStoredRun(codec, storage, keys, runId, previous, events);
@@ -357,8 +383,16 @@ export async function failStoredRun<Snapshot>(
     phase: run.phase === "reconciliation-required" ? "executing" : run.phase,
     failure,
   } satisfies StoredRunV1<Snapshot>);
+  const records: Record<string, unknown> = {
+    [keys.run]: structuredClone(storedRunRecordV2(failed)),
+  };
+  const intent = alreadyFailed ? undefined : failureNotification?.(failed);
+  if (intent) {
+    records[`${keys.notificationPrefix}${intent.notificationId}`] =
+      structuredClone(intent);
+  }
   await new SessionEventLog(storage).rewrite(run.sessionId, latestEvents);
-  await storage.put({ [keys.run]: structuredClone(storedRunRecordV2(failed)) });
+  await storage.put(records);
   if ((await storage.get<string>(keys.activeRun)) === runId) {
     await storage.delete(keys.activeRun);
   }