@frockbot/kernel-contracts 0.3.5 → 0.3.7

package/package.json

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

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./isolate-context-catalog.generated.js";
 export * from "./loop-events.js";
 export * from "./model-invocation.js";
 export * from "./prompt-assembly.js";
+export * from "./remote.js";
 export * from "./send-to-user.js";
 export * from "./session.js";
 export * from "./skills.js";

package/src/model-invocation.ts

@@ -14,14 +14,75 @@ 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";
       events: readonly LlmStreamEvent[];
     }
   | {
+      /**
+       * The effect may still exist at the provider but cannot be read right
+       * now. The run parks and can be reconciled again later.
+       */
       status: "unavailable";
       reason: string;
+    }
+  | {
+      /**
+       * The provider keeps no durable copy of this effect, so no later attempt
+       * can do better. The run settles as a failure — with whatever text was
+       * already journaled preserved — rather than parking forever on a
+       * retrieval that will never succeed.
+       */
+      status: "not-retrievable";
+      reason: string;
     };
 
 export interface LlmReconciliationCapability {

package/src/remote.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import {
+  RemoteCallTimeoutError,
+  remoteCallV1,
+  retryOnceV1,
+  withDeadlineV1,
+} from "./remote.js";
+
+describe("a remote call is bounded", () => {
+  test("a call that never answers is abandoned, not waited on", async () => {
+    const signals: AbortSignal[] = [];
+    const call = await withDeadlineV1(
+      "the ledger",
+      (signal) => {
+        signals.push(signal);
+        return new Promise<never>(() => {});
+      },
+      10,
+    ).catch((error: unknown) => error);
+
+    expect(call).toBeInstanceOf(RemoteCallTimeoutError);
+    expect((call as Error).message).toContain("the ledger");
+    // The binding is told, even though the deadline is a bound on waiting and
+    // not a guarantee that the effect did not land.
+    expect(signals[0]!.aborted).toBe(true);
+  });
+
+  test("an answer inside the deadline is returned unchanged", async () => {
+    expect(
+      await withDeadlineV1("the ledger", () => Promise.resolve(7), 1_000),
+    ).toBe(7);
+  });
+
+  test("a transient failure is tried once more, and only once", async () => {
+    let attempts = 0;
+    expect(
+      await retryOnceV1(() => {
+        attempts += 1;
+        return attempts === 1
+          ? Promise.reject(new Error("blip"))
+          : Promise.resolve("second");
+      }),
+    ).toBe("second");
+    expect(attempts).toBe(2);
+
+    let always = 0;
+    await expect(
+      retryOnceV1(() => {
+        always += 1;
+        return Promise.reject(new Error("really down"));
+      }),
+    ).rejects.toThrow("really down");
+    expect(always).toBe(2);
+  });
+
+  test("a hung call is retried under its own fresh deadline", async () => {
+    let attempts = 0;
+    await expect(
+      remoteCallV1(
+        "the memory index",
+        () => {
+          attempts += 1;
+          return new Promise<never>(() => {});
+        },
+        10,
+      ),
+    ).rejects.toBeInstanceOf(RemoteCallTimeoutError);
+    expect(attempts).toBe(2);
+  });
+});

package/src/remote.ts

@@ -0,0 +1,76 @@
+/**
+ * Bounds on a remote call.
+ *
+ * `MEMORY_FILES` and `MEMORY_INDEX` are remote bindings even in development,
+ * and so are the cross-Durable-Object ledger and membership calls beside them.
+ * Every one of those seams used to be a bare `await`: no deadline, no retry.
+ * A hung binding therefore hung the whole Turn to the platform limit, and a
+ * blip that a second attempt would have survived failed a Turn instead.
+ *
+ * These are two small functions rather than a client wrapper on purpose. The
+ * seams are in several Packages and take several shapes, and what they all
+ * need is the same two sentences: do not wait forever, and try a transient
+ * failure once more.
+ */
+
+/** How long one remote call may take before it is abandoned. */
+export const REMOTE_CALL_TIMEOUT_MS_V1 = 10_000;
+
+export class RemoteCallTimeoutError extends Error {
+  constructor(label: string, timeoutMs: number) {
+    super(`${label} did not answer within ${timeoutMs}ms`);
+    this.name = "RemoteCallTimeoutError";
+  }
+}
+
+/**
+ * Runs one remote call under a deadline.
+ *
+ * The deadline is a bound on *waiting*, not a cancellation: a binding that
+ * ignores its `AbortSignal` may still land its effect, which is why every
+ * caller of this treats a timeout the way it treats any other uncertain
+ * outcome rather than assuming nothing happened.
+ */
+export async function withDeadlineV1<T>(
+  label: string,
+  call: (signal: AbortSignal) => Promise<T>,
+  timeoutMs: number = REMOTE_CALL_TIMEOUT_MS_V1,
+): Promise<T> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expiry = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new RemoteCallTimeoutError(label, timeoutMs));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([call(controller.signal), expiry]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/**
+ * Runs a call, and runs it once more if the first attempt threw.
+ *
+ * One retry, not a backoff schedule: the caller is inside a Turn a person is
+ * waiting on, and the failure this recovers from is a blip. Anything that
+ * fails twice is a real failure and is reported as one.
+ */
+export async function retryOnceV1<T>(call: () => Promise<T>): Promise<T> {
+  try {
+    return await call();
+  } catch {
+    return call();
+  }
+}
+
+/** A remote call under a deadline, attempted twice. */
+export function remoteCallV1<T>(
+  label: string,
+  call: (signal: AbortSignal) => Promise<T>,
+  timeoutMs: number = REMOTE_CALL_TIMEOUT_MS_V1,
+): Promise<T> {
+  return retryOnceV1(() => withDeadlineV1(label, call, timeoutMs));
+}

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;
@@ -493,7 +514,8 @@ export interface SessionEventMap {
     facts: Array<{
       scope: MemoryScopeNameV1;
       projectId: string;
-      tier: "profile" | "log";
+      /** The tier it was written as; a note lives in the log file. */
+      tier: "profile" | "log" | "note";
       via: string;
       learnedAt: string;
       text: string;
@@ -527,7 +549,14 @@ export interface SessionEventMap {
     action: "write" | "forget";
     scope: MemoryScopeNameV1;
     projectId: string;
-    tier: "profile" | "log" | "note";
+    /**
+     * `pending` when the intent cannot name a tier yet. A forget may rewrite
+     * the profile file, one or more log files, or write a retraction, and
+     * which it is, is not known until it has run; the `memory/written` events
+     * that follow name the real tier and path.
+     */
+    tier: "profile" | "log" | "note" | "pending";
+    /** Empty when the intent cannot name a path yet, for the same reason. */
     path: string;
     contentHash: string;
   };
@@ -780,6 +809,17 @@ function memoryTier(value: unknown, label: string): void {
   }
 }
 
+/**
+ * The tier an *intent* names. A forget does not know which files it will
+ * touch until it has run — it may rewrite the profile file, one or more log
+ * files, or write a retraction — so `pending` is the honest answer, and the
+ * `memory/written` events that follow name the real tier and path.
+ */
+function memoryIntentTier(value: unknown, label: string): void {
+  if (value === "pending") return;
+  memoryTier(value, label);
+}
+
 function memoryAction(value: unknown, label: string): void {
   if (value !== "write" && value !== "forget") {
     throw new Error(`${label} is invalid`);
@@ -1327,6 +1367,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,
@@ -1573,9 +1643,9 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
         );
         memoryScope(entry.scope, `${label}.scope`);
         eventString(entry.projectId, `${label}.projectId`, true);
-        if (entry.tier !== "profile" && entry.tier !== "log") {
-          throw new Error(`${label}.tier is invalid`);
-        }
+        // `note` too: a note lives in the log file, and recording it as `log`
+        // left a reader of the durable event unable to tell the tiers apart.
+        memoryTier(entry.tier, `${label}.tier`);
         eventString(entry.via, `${label}.via`, true);
         eventString(entry.learnedAt, `${label}.learnedAt`);
         eventString(entry.text, `${label}.text`);
@@ -1630,8 +1700,8 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
       memoryAction(event.action, "session event.action");
       memoryScope(event.scope, "session event.scope");
       eventString(event.projectId, "session event.projectId", true);
-      memoryTier(event.tier, "session event.tier");
-      eventString(event.path, "session event.path");
+      memoryIntentTier(event.tier, "session event.tier");
+      eventString(event.path, "session event.path", true);
       eventString(event.contentHash, "session event.contentHash");
       break;
     case "memory/written":

package/src/workspace.ts

@@ -313,7 +313,18 @@ export function isWorkspaceConflictV1(
 }
 
 export type WorkspaceWriteOutcomeV1 =
-  | { status: "ok"; generation: WorkspaceGenerationV1 }
+  | {
+      status: "ok";
+      generation: WorkspaceGenerationV1;
+      /**
+       * The bytes are durable but the generation ledger has not recorded them
+       * yet. A write is still `ok`: the fact is the bytes, and the ledger is
+       * the index of the fact. The generation travels beside the bytes, so
+       * `reconcile` repairs the entry on its own; a caller that wants to say
+       * so may, and a caller that does not may ignore it.
+       */
+      ledgerPending?: true;
+    }
   | WorkspaceConflictV1
   | WorkspaceFailureV1;