@frockbot/kernel-contracts 0.3.13 → 0.3.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-contracts",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "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/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,