@frockbot/kernel-contracts 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-contracts",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "private": false,
   "type": "module",
   "exports": {

package/src/model-invocation.ts

@@ -14,6 +14,53 @@ export class LlmEffectNotStartedError extends Error {
   }
 }
 
+/**
+ * A model request that ran out of time.
+ *
+ * Two deadlines, because they fail differently. `first-byte` is a provider that
+ * accepted the request and said nothing: the request may well be running, so
+ * the outcome is uncertain and the run settles on that. `idle` is a stream that
+ * started and then stopped mid-answer, which is the same uncertainty arriving
+ * later, with words already on screen.
+ *
+ * Either is a real answer where before there was none: a Turn with no deadline
+ * anywhere hung for seventeen minutes showing nothing at all.
+ */
+export class ModelRequestDeadlineError extends Error {
+  constructor(
+    readonly phase: "first-byte" | "idle",
+    readonly milliseconds: number,
+  ) {
+    super(
+      phase === "first-byte"
+        ? `Model request produced nothing within ${Math.round(milliseconds / 1000)}s`
+        : `Model response stalled for ${Math.round(milliseconds / 1000)}s`,
+    );
+    this.name = "ModelRequestDeadlineError";
+  }
+}
+
+/** Deadlines a provider applies to one model request. */
+export interface ModelRequestDeadlinesV1 {
+  /** Time allowed from sending the request to the first stream event. */
+  firstByteMs: number;
+  /** Time allowed between two stream events once the answer has started. */
+  idleMs: number;
+}
+
+/**
+ * The defaults every provider gets unless its Package names others.
+ *
+ * Two minutes to say anything at all is generous for a chat completion and
+ * still an order of magnitude inside the wall-clock a person will wait; the
+ * same allowance between chunks tolerates a slow tool-call assembly without
+ * tolerating a dead socket.
+ */
+export const MODEL_REQUEST_DEADLINES_V1: ModelRequestDeadlinesV1 = {
+  firstByteMs: 120_000,
+  idleMs: 120_000,
+};
+
 export type LlmReconciliationOutcome =
   | {
       status: "recovered";

package/src/session.test.ts

@@ -368,6 +368,32 @@ describe("SessionStore", () => {
     ]);
   });
 
+  test("a failed durable write is reported and does not stop later writes", async () => {
+    const persisted: string[][] = [];
+    let failNext = true;
+    const root = await createStore(undefined, {
+      persistEvents: async (_sessionId, events) => {
+        await Promise.resolve();
+        if (failNext) {
+          failNext = false;
+          throw new Error("storage hiccup");
+        }
+        persisted.push(events.map((event) => event.type));
+      },
+    });
+    const session = root.sessions.create("durable-session");
+
+    // The Turn fails loudly rather than carrying on in memory over a log that
+    // silently stopped being written.
+    await expect(session.flush()).rejects.toThrow("storage hiccup");
+
+    // And the chain is not poisoned: chaining with `then` alone made every
+    // later write skip its callback for the life of the Session.
+    session.append({ type: "turn/start", turn: 1 });
+    await session.flush().catch(() => undefined);
+    expect(persisted).toEqual([["turn/start"]]);
+  });
+
   test("rehydrates a session and continues its sequence", async () => {
     const firstRoot = await createStore();
     const first = firstRoot.sessions.create("durable-session");

package/src/session.ts

@@ -210,6 +210,8 @@ export class Session {
   #emit: (envelope: SessionEventEnvelope) => void;
   #persist?: PersistSessionEvents;
   #pendingPersistence: Promise<void> = Promise.resolve();
+  /** The first durable write that failed. Every later `flush` reports it. */
+  #persistFailure: Error | undefined;
   /**
    * Resolved attachment bytes, keyed by content hash, held only while this
    * Session is resident.
@@ -273,15 +275,27 @@ export class Session {
     for (const event of events) this.#emit({ sessionId: this.id, event });
     if (this.#persist && events.length > 0) {
       const durableEvents = structuredClone(events);
-      this.#pendingPersistence = this.#pendingPersistence.then(() =>
-        this.#persist?.(this.id, durableEvents),
-      );
+      // A chain that has already rejected must still attempt this write.
+      // Chaining with `then` alone skipped the callback for the life of the
+      // Session — no event was ever written again while the loop carried on
+      // in memory — and left the rejection unhandled between an append and
+      // the next flush. The failure is remembered instead, and `flush` throws
+      // it, so the Turn fails loudly exactly once.
+      const pending = this.#pendingPersistence
+        .catch(() => undefined)
+        .then(() => this.#persist?.(this.id, durableEvents));
+      this.#pendingPersistence = pending;
+      void pending.catch((error: unknown) => {
+        this.#persistFailure ??=
+          error instanceof Error ? error : new Error(String(error));
+      });
     }
     return events;
   }
 
-  flush(): Promise<void> {
-    return this.#pendingPersistence;
+  async flush(): Promise<void> {
+    await this.#pendingPersistence.catch(() => undefined);
+    if (this.#persistFailure) throw this.#persistFailure;
   }
 
   /**
@@ -410,10 +424,16 @@ export class Session {
         });
       }
     }
+    // An unresolved model request holds the step open — but only while the run
+    // might still resume and let that outcome land. Closing the turn means it
+    // never will, and a `turn/end` over an open step is itself invalid: it
+    // produced "turn 1 ended while step 1 is open" and left the log as unusable
+    // as the open turn it was meant to repair.
     if (
       openStep &&
-      unresolvedModelRequests.size === 0 &&
-      (closeTurn || !openStepHasAssistant)
+      (closeTurn
+        ? true
+        : unresolvedModelRequests.size === 0 && !openStepHasAssistant)
     ) {
       repairs.push({ type: "step/end", ...openStep, outcome: "interrupted" });
     }

package/src/types.ts

@@ -170,7 +170,12 @@ export function turnEndReason(value: unknown): string | undefined {
   return bounded.length > 0 ? bounded : undefined;
 }
 
-/** The failure text a User sees for a Turn that did not complete. */
+/**
+ * The failure text recorded against a Turn that did not complete. It names the
+ * outcome and the provider's own reason, which the debug surface and the API
+ * both need. It is a diagnostic, not copy: the client never renders it into the
+ * conversation — see `runFailureCopyV1` in the shell's client.
+ */
 export function turnFailureMessage(
   outcome: TurnOutcome,
   reason?: string,
@@ -370,6 +375,22 @@ export interface SessionEventMap {
     contentHash: string;
     generationId: string;
   };
+  /**
+   * A recorded Package effect intent that ended without its outcome: the host
+   * refused, or the attempt threw. Every `package/*-intent` closes with either
+   * its outcome event or this one, so the session log never says an effect was
+   * intended and then falls silent about how it ended — which is exactly what
+   * the intent/outcome pair is for (finding F12).
+   */
+  "package/effect-failed": {
+    turn: number;
+    step: number;
+    effectId: string;
+    effect: "author" | "undo" | "catalog-change";
+    reason: string;
+    /** The durable failure record, when the host wrote one. */
+    failureId?: string;
+  };
   /** A Bot-isolate loop hook failed open for one invocation. */
   "package/hook-failed": {
     packageId: string;
@@ -1327,6 +1348,36 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
       eventString(event.contentHash, "session event.contentHash");
       eventString(event.generationId, "session event.generationId");
       break;
+    case "package/effect-failed":
+      requireEventKeys(
+        event,
+        keys(
+          "turn",
+          "step",
+          "effectId",
+          "effect",
+          "reason",
+          ...(Object.hasOwn(event, "failureId") ? ["failureId"] : []),
+        ),
+        "session event",
+      );
+      turn();
+      step();
+      eventString(event.effectId, "session event.effectId");
+      if (
+        event.effect !== "author" &&
+        event.effect !== "undo" &&
+        event.effect !== "catalog-change"
+      ) {
+        throw new Error(
+          'session event.effect must be "author", "undo" or "catalog-change"',
+        );
+      }
+      eventString(event.reason, "session event.reason", true);
+      if (Object.hasOwn(event, "failureId")) {
+        eventString(event.failureId, "session event.failureId");
+      }
+      break;
     case "package/hook-failed":
       requireEventKeys(
         event,
@@ -1478,7 +1529,11 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
         const label = `session event.refusals[${index}]`;
         const entry = eventRecord(refusal, label);
         requireEventKeys(entry, ["path", "reason"], label);
-        eventString(entry.path, `${label}.path`);
+        // A refusal that names no path is still a refusal — the read was
+        // declined at the root, and the reason is the part that matters.
+        // Rejecting it here killed the Turn *after* the event was appended,
+        // which left the durable log open inside that Turn and wedged the Bot.
+        eventString(entry.path, `${label}.path`, true);
         eventString(entry.reason, `${label}.reason`);
       });
       break;