@frockbot/kernel-contracts 0.3.5 → 0.3.6

package/package.json

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

@@ -424,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,