@frockbot/kernel-contracts 0.3.6 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-contracts",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "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,6 +14,38 @@ export class LlmEffectNotStartedError extends Error {
   }
 }
 
+/**
+ * What a person is told when a model request produced nothing at all.
+ *
+ * The same register as the Turn deadline copy: what happened, and what to do
+ * about it. The phase, the provider and the millisecond count are diagnostics
+ * and belong in the log, not on a person's screen.
+ */
+export const MODEL_FIRST_BYTE_DEADLINE_REASON_V1 =
+  "The model did not start replying within 2 minutes and the request was stopped. Try sending it again.";
+
+/** What a person is told when a reply started and then went silent. */
+export const MODEL_IDLE_DEADLINE_REASON_V1 =
+  "The model stopped part-way through its reply and went quiet for a minute, so the request was stopped. Try sending it again.";
+
+/**
+ * Time allowed from sending a model request to its first stream event.
+ *
+ * Two minutes to say anything at all is generous for a chat completion and
+ * still far inside the fifteen-minute Turn deadline, which before this was the
+ * only bound anywhere and far too long to read as an answer.
+ */
+export const MODEL_FIRST_BYTE_DEADLINE_MS_V1 = 120_000;
+
+/**
+ * Time allowed between two stream events once the answer has started.
+ *
+ * Shorter than the first-byte allowance on purpose: a stream that has already
+ * produced a chunk has proved the model is generating, so a minute of silence
+ * after that is a dead socket rather than a slow start.
+ */
+export const MODEL_IDLE_DEADLINE_MS_V1 = 60_000;
+
 /**
  * A model request that ran out of time.
  *
@@ -24,7 +56,8 @@ export class LlmEffectNotStartedError extends Error {
  * 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.
+ * anywhere hung for seventeen minutes showing nothing at all. The message is
+ * the copy a person reads, so it says nothing the caller could vary.
  */
 export class ModelRequestDeadlineError extends Error {
   constructor(
@@ -33,8 +66,8 @@ export class ModelRequestDeadlineError extends Error {
   ) {
     super(
       phase === "first-byte"
-        ? `Model request produced nothing within ${Math.round(milliseconds / 1000)}s`
-        : `Model response stalled for ${Math.round(milliseconds / 1000)}s`,
+        ? MODEL_FIRST_BYTE_DEADLINE_REASON_V1
+        : MODEL_IDLE_DEADLINE_REASON_V1,
     );
     this.name = "ModelRequestDeadlineError";
   }
@@ -48,17 +81,10 @@ export interface ModelRequestDeadlinesV1 {
   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.
- */
+/** The defaults every provider gets unless its Package names others. */
 export const MODEL_REQUEST_DEADLINES_V1: ModelRequestDeadlinesV1 = {
-  firstByteMs: 120_000,
-  idleMs: 120_000,
+  firstByteMs: MODEL_FIRST_BYTE_DEADLINE_MS_V1,
+  idleMs: MODEL_IDLE_DEADLINE_MS_V1,
 };
 
 export type LlmReconciliationOutcome =
@@ -67,8 +93,22 @@ export type LlmReconciliationOutcome =
       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/types.ts

@@ -514,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;
@@ -548,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;
   };
@@ -801,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`);
@@ -1624,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`);
@@ -1681,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;