@frockbot/kernel-contracts 0.3.14 → 0.3.16

package/package.json

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

package/src/model-invocation.ts

@@ -7,9 +7,49 @@ export interface DurableModelEffect {
   request: NormalizedModelRequest;
 }
 
-export class LlmEffectNotStartedError extends Error {
+export const MODEL_PROVIDER_FAILURE_REASON_MAX_LENGTH_V1 = 500;
+
+export type ModelProviderFailureClassV1 = "transient" | "permanent" | "unknown";
+
+/** Keep provider diagnostics useful without letting an envelope grow the log. */
+export function boundedModelProviderReasonV1(reason: unknown): string {
+  const value =
+    typeof reason === "string" && reason.trim()
+      ? reason.trim()
+      : "The model provider did not give a reason";
+  return value.slice(0, MODEL_PROVIDER_FAILURE_REASON_MAX_LENGTH_V1);
+}
+
+/** A definitive provider failure raised before response bytes were emitted. */
+export class ModelProviderFailureError extends Error {
+  readonly classification: ModelProviderFailureClassV1;
+  readonly providerReason: string;
+  readonly retryAfterMs?: number;
+
+  constructor(input: {
+    classification: ModelProviderFailureClassV1;
+    reason: unknown;
+    retryAfterMs?: number;
+  }) {
+    const reason = boundedModelProviderReasonV1(input.reason);
+    super(reason);
+    this.name = "ModelProviderFailureError";
+    this.classification = input.classification;
+    this.providerReason = reason;
+    if (
+      input.retryAfterMs !== undefined &&
+      Number.isSafeInteger(input.retryAfterMs) &&
+      input.retryAfterMs >= 0
+    ) {
+      this.retryAfterMs = input.retryAfterMs;
+    }
+  }
+}
+
+/** @deprecated Providers should raise a classified failure instead. */
+export class LlmEffectNotStartedError extends ModelProviderFailureError {
   constructor(message: string) {
-    super(message);
+    super({ classification: "unknown", reason: message });
     this.name = "LlmEffectNotStartedError";
   }
 }

package/src/session.test.ts

@@ -39,6 +39,26 @@ afterEach(async () => {
   await Promise.all(roots.splice(0).map((root) => root.fiber.dispose()));
 });
 
+test("a model retry is a small exact durable session event", () => {
+  const event = {
+    type: "model/retry",
+    turn: 1,
+    step: 2,
+    attempt: 3,
+    classification: "transient",
+    delayMs: 1_000,
+    seq: 0,
+    timestamp,
+  } as const;
+  expect(decodeSessionEvent(event)).toEqual(event);
+  expect(() =>
+    decodeSessionEvent({ ...event, reason: "large envelope" }),
+  ).toThrow(/invalid fields/);
+  expect(() =>
+    decodeSessionEvent({ ...event, classification: "maybe" }),
+  ).toThrow(/classification is invalid/);
+});
+
 test("a Bot-isolate hook failure is an exact durable session event", () => {
   const event = {
     type: "package/hook-failed",

package/src/session.ts

@@ -216,8 +216,8 @@ export class Session {
    * Resolved attachment bytes, keyed by content hash, held only while this
    * Session is resident.
    *
-   * The session event log is one Durable Object value and a screenshot in it
-   * would be a durable record that grows past what the object can hold, so an
+   * A screenshot in the session log would multiply durable storage and prompt
+   * size even though the Bot authority pages and chunks large events, so an
    * attachment records a Workspace path and a content hash and nothing else.
    * A tool that produced the bytes offers them here, and the request derived
    * while they are still held carries them to a model that can see images. On

package/src/tool-attachments.test.ts

@@ -1,10 +1,9 @@
 // Tool result attachments: what may be recorded, and what may not.
 //
 // The one rule worth a suite of its own is that resolved bytes are never
-// durable. The session event log is one Durable Object value; a base64
-// screenshot recorded in it would be a record that grows past what the object
-// can hold, so the decoder refuses `dataBase64` on the durable side rather
-// than trimming it somewhere further down.
+// durable. A base64 screenshot recorded in the paged session log would still
+// multiply durable storage and model-request size, so the decoder refuses
+// `dataBase64` on the durable side rather than trimming it further down.
 import { describe, expect, test } from "bun:test";
 import {
   decodeToolAttachmentsV1,

package/src/types.ts

@@ -308,6 +308,14 @@ export interface SessionEventMap {
     requestId: string;
     reason: string;
   };
+  /** One small durable explanation for why the next model attempt waited. */
+  "model/retry": {
+    turn: number;
+    step: number;
+    attempt: number;
+    classification: "transient" | "permanent" | "unknown";
+    delayMs: number;
+  };
   "model/reconciliation-required": {
     turn: number;
     step: number;
@@ -1272,6 +1280,24 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
       requestId();
       eventString(event.reason, "session event.reason");
       break;
+    case "model/retry":
+      requireEventKeys(
+        event,
+        keys("turn", "step", "attempt", "classification", "delayMs"),
+        "session event",
+      );
+      turn();
+      step();
+      eventInteger(event.attempt, "session event.attempt", 2);
+      if (
+        event.classification !== "transient" &&
+        event.classification !== "permanent" &&
+        event.classification !== "unknown"
+      ) {
+        throw new Error("session event.classification is invalid");
+      }
+      eventInteger(event.delayMs, "session event.delayMs", 0);
+      break;
     case "assistant/chunk":
       requireEventKeys(
         event,