@frockbot/kernel-contracts 0.3.11 → 0.3.13

package/package.json

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

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./send-to-user.js";
 export * from "./session.js";
 export * from "./skills.js";
 export * from "./tool-execution.js";
+export * from "./turn-deadline.js";
 export * from "./turn-history.js";
 export * from "./types.js";
 export * from "./workspace.js";

package/src/session.test.ts

@@ -55,6 +55,54 @@ test("a Bot-isolate hook failure is an exact durable session event", () => {
   );
 });
 
+test("a compaction is an exact durable session event", () => {
+  const intent = {
+    type: "conversation/compaction-intent",
+    effectId: "compaction-1",
+    throughTurn: 6,
+    provider: "ollama-cloud",
+    model: "kimi-k2",
+    seq: 0,
+    timestamp,
+  } as const;
+  expect(decodeSessionEvent(intent)).toEqual(intent);
+  expect(() => decodeSessionEvent({ ...intent, turn: 6 })).toThrow(
+    /invalid fields/,
+  );
+  const compacted = {
+    type: "conversation/compacted",
+    effectId: "compaction-1",
+    fromTurn: 1,
+    throughTurn: 6,
+    summary: "## Summary\nThey shipped it.",
+    identifiers: ["applet-9f2c"],
+    provider: "ollama-cloud",
+    model: "kimi-k2",
+    seq: 1,
+    timestamp,
+  } satisfies SessionEvent;
+  expect(decodeSessionEvent(structuredClone(compacted))).toEqual(compacted);
+  // A range that ends before it starts is not a range.
+  expect(() => decodeSessionEvent({ ...compacted, fromTurn: 9 })).toThrow(
+    /throughTurn is invalid/,
+  );
+  expect(() =>
+    decodeSessionEvent({ ...compacted, summary: "x".repeat(20_000) }),
+  ).toThrow(/summary is too long/);
+  expect(() =>
+    decodeSessionEvent({ ...compacted, identifiers: "applet-9f2c" }),
+  ).toThrow(/bounded array/);
+  const failed = {
+    type: "conversation/compaction-failed",
+    effectId: "compaction-1",
+    throughTurn: 6,
+    reason: "the summariser ran past its deadline",
+    seq: 2,
+    timestamp,
+  } as const;
+  expect(decodeSessionEvent(failed)).toEqual(failed);
+});
+
 describe("SessionStore", () => {
   test("accepts resumable tool crash states only while their step is open", () => {
     const assistant = [

package/src/turn-deadline.ts

@@ -0,0 +1,16 @@
+/**
+ * The longest a single Turn may run before the loop stops waiting for it.
+ *
+ * Nothing bounded a Turn's wall clock before this: one hung for seventeen
+ * minutes with an animated avatar and nothing else, and would have hung until
+ * the isolate died. Fifteen minutes is well past any Turn a person is watching
+ * and well inside the point at which they have concluded the product is broken.
+ *
+ * It lives in the contracts rather than in the loop that enforces it because
+ * two parties need the same number: the loop, which aborts on it, and every
+ * reader that has to decide whether a run still marked `running` can possibly
+ * still be running. A record older than this deadline is not working — whatever
+ * its status field says — and a reader that used a different number would
+ * either leave a dead Turn wearing the activity ring or cut a live one off.
+ */
+export const TURN_DEADLINE_MS_V1 = 15 * 60 * 1000;

package/src/types.ts

@@ -155,6 +155,18 @@ export type TurnOutcome = StepOutcome;
 /** Longest `reason` a `turn/end` event may carry. */
 export const TURN_END_REASON_MAX_LENGTH = 500;
 
+/**
+ * Bounds on one `conversation/compacted` event (ADR 0030).
+ *
+ * A summary is model output that is stored durably and replayed into every
+ * later request of the conversation, so it is bounded here rather than trusted
+ * to be short: the whole point of compaction is that the window stops growing.
+ */
+export const COMPACTION_SUMMARY_MAX_LENGTH = 12_000;
+export const COMPACTION_IDENTIFIERS_MAX = 200;
+export const COMPACTION_IDENTIFIER_MAX_LENGTH = 400;
+export const COMPACTION_FAILURE_REASON_MAX_LENGTH = 500;
+
 /**
  * Truncates a failure description to what a `turn/end` `reason` accepts.
  * Returns `undefined` when nothing describable remains.
@@ -755,6 +767,55 @@ export interface SessionEventMap {
     taskId: string;
     requestedBy: "bot" | "user";
   };
+  /**
+   * The durable intent to compact this conversation, recorded before the
+   * summariser model call it fences (ADR 0030). It carries no `turn`: a
+   * compaction is evaluated *after* a Turn has ended, so it belongs to the
+   * conversation rather than to any step of it — the `bot/renamed` shape.
+   *
+   * `throughTurn` is the last Turn the attempt covers. A compaction always
+   * covers a prefix, so the range is that one number, and it is also the
+   * idempotency key: an intent is refused when a `conversation/compacted`
+   * already covers it.
+   */
+  "conversation/compaction-intent": {
+    effectId: string;
+    throughTurn: number;
+    provider: string;
+    model: string;
+  };
+  /**
+   * One summary of Turns `fromTurn` through `throughTurn`, computed once and
+   * replayed on every later request. The newest such event supersedes every
+   * earlier one, because each covers a prefix and the summariser folds the
+   * previous summary into the range it extends.
+   *
+   * `identifiers` is the summariser's own "Identifiers mentioned" list, kept
+   * as a field rather than left inside the prose: an opaque id that a summary
+   * paraphrases produces a later tool call with a plausible-looking wrong
+   * argument, so what the model was asked to preserve is what the log records.
+   */
+  "conversation/compacted": {
+    effectId: string;
+    fromTurn: number;
+    throughTurn: number;
+    summary: string;
+    identifiers: string[];
+    provider: string;
+    model: string;
+  };
+  /**
+   * A compaction intent that produced no summary — the summariser failed, ran
+   * past its deadline, answered unusably, or a restart interrupted it. Never
+   * fatal: the conversation carries on under the whole-Turn eviction ADR 0027
+   * already applies, and the next attempt is spaced by backoff counted from
+   * these events.
+   */
+  "conversation/compaction-failed": {
+    effectId: string;
+    throughTurn: number;
+    reason: string;
+  };
   "step/end": { turn: number; step: number; outcome: StepOutcome };
   /**
    * `reason` states why a Turn ended in a non-`completed` outcome, so the
@@ -2026,6 +2087,82 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
       }
       break;
     }
+    case "conversation/compaction-intent":
+      requireEventKeys(
+        event,
+        keys("effectId", "throughTurn", "provider", "model"),
+        "session event",
+      );
+      eventString(event.effectId, "session event.effectId");
+      eventInteger(event.throughTurn, "session event.throughTurn", 1);
+      eventString(event.provider, "session event.provider");
+      eventString(event.model, "session event.model");
+      break;
+    case "conversation/compacted": {
+      requireEventKeys(
+        event,
+        keys(
+          "effectId",
+          "fromTurn",
+          "throughTurn",
+          "summary",
+          "identifiers",
+          "provider",
+          "model",
+        ),
+        "session event",
+      );
+      eventString(event.effectId, "session event.effectId");
+      const fromTurn = eventInteger(
+        event.fromTurn,
+        "session event.fromTurn",
+        1,
+      );
+      const throughTurn = eventInteger(
+        event.throughTurn,
+        "session event.throughTurn",
+        1,
+      );
+      if (throughTurn < fromTurn) {
+        throw new Error("session event.throughTurn is invalid");
+      }
+      const summary = eventString(event.summary, "session event.summary");
+      if (summary.length > COMPACTION_SUMMARY_MAX_LENGTH) {
+        throw new Error("session event.summary is too long");
+      }
+      if (
+        !Array.isArray(event.identifiers) ||
+        event.identifiers.length > COMPACTION_IDENTIFIERS_MAX
+      ) {
+        throw new Error("session event.identifiers must be a bounded array");
+      }
+      event.identifiers.forEach((identifier, index) => {
+        const label = `session event.identifiers[${index}]`;
+        if (
+          eventString(identifier, label).length >
+          COMPACTION_IDENTIFIER_MAX_LENGTH
+        ) {
+          throw new Error(`${label} is too long`);
+        }
+      });
+      eventString(event.provider, "session event.provider");
+      eventString(event.model, "session event.model");
+      break;
+    }
+    case "conversation/compaction-failed": {
+      requireEventKeys(
+        event,
+        keys("effectId", "throughTurn", "reason"),
+        "session event",
+      );
+      eventString(event.effectId, "session event.effectId");
+      eventInteger(event.throughTurn, "session event.throughTurn", 1);
+      const reason = eventString(event.reason, "session event.reason");
+      if (reason.length > COMPACTION_FAILURE_REASON_MAX_LENGTH) {
+        throw new Error("session event.reason is too long");
+      }
+      break;
+    }
     case "step/end":
       requireEventKeys(event, keys("turn", "step", "outcome"), "session event");
       turn();