@frockbot/kernel-do 0.3.15 → 0.3.17

package/src/session-log-size.test.ts

@@ -0,0 +1,250 @@
+import { describe, expect, test } from "bun:test";
+import {
+  bootstrapGeneration,
+  type CompositionGenerationV1,
+} from "@frockbot/kernel-composition/generation";
+import { Session, type SessionEvent } from "@frockbot/kernel-contracts";
+import {
+  BotDurableAuthority,
+  type BotDurableAuthorityHooks,
+} from "./authority.ts";
+import { MemoryStorage } from "./memory-storage.fixture.ts";
+import { createStoredRunCodecV1, type StoredRunV1 } from "./run-records.ts";
+
+const SQLITE_VALUE_LIMIT_BYTES = 2 * 1024 * 1024;
+const LARGE_REQUEST_BYTES = 80_000;
+const STEPS = 30;
+const SESSION_ID = "user-1:primary";
+
+const codec = createStoredRunCodecV1<undefined>({
+  decodeRunId: (value) => String(value),
+  decodeConfigurationSnapshot: () => undefined,
+});
+
+/** A storage double that enforces Durable Object SQLite's per-value ceiling. */
+class SqliteLimitedMemoryStorage extends MemoryStorage {
+  readonly rejectedKeys: string[] = [];
+
+  override put(
+    key: string | Record<string, unknown>,
+    value?: unknown,
+  ): Promise<void> {
+    const entries =
+      typeof key === "string" ? [[key, value] as const] : Object.entries(key);
+    for (const [entryKey, entry] of entries) {
+      const bytes = new TextEncoder().encode(JSON.stringify(entry)).byteLength;
+      if (bytes > SQLITE_VALUE_LIMIT_BYTES) {
+        this.rejectedKeys.push(entryKey);
+        throw new Error("string or blob too big: SQLITE_TOOBIG");
+      }
+    }
+    return super.put(key, value);
+  }
+
+  override async transaction<T>(
+    callback: (storage: MemoryStorage) => Promise<T>,
+  ): Promise<T> {
+    const before = structuredClone([...this.values.entries()]);
+    try {
+      return await callback(this);
+    } catch (error) {
+      this.values.clear();
+      for (const [key, value] of before) this.values.set(key, value);
+      throw error;
+    }
+  }
+}
+
+function bootstrap(): Promise<CompositionGenerationV1> {
+  return bootstrapGeneration(
+    [
+      {
+        packageId: "shell",
+        specifier: "@frockbot/plugin-shell",
+        version: "0.0.1",
+        manifest: { id: "shell", version: "0.0.1" },
+      },
+    ],
+    { createdAt: "2026-09-04T00:00:00.000Z" },
+  );
+}
+
+function legacyEvents(): SessionEvent[] {
+  const session = new Session(SESSION_ID, () => {});
+  session.appendBatch([
+    { type: "turn/start", turn: 1 },
+    { type: "step/start", turn: 1, step: 1 },
+    {
+      type: "user/message",
+      turn: 1,
+      step: 1,
+      messageId: "legacy-message",
+      text: "Earlier work",
+    },
+    {
+      type: "model/request",
+      turn: 1,
+      step: 1,
+      request: {
+        requestId: "legacy-request",
+        provider: "fake",
+        model: "large-context",
+        system: "p".repeat(1_900_000),
+        messages: [{ role: "user", content: "Earlier work" }],
+        tools: [],
+      },
+    },
+    {
+      type: "assistant/message",
+      turn: 1,
+      step: 1,
+      requestId: "legacy-request",
+      text: "Done earlier.",
+      toolCalls: [],
+    },
+    { type: "step/end", turn: 1, step: 1, outcome: "completed" },
+    { type: "turn/end", turn: 1, outcome: "completed" },
+  ]);
+  return [...session.events];
+}
+
+function legacyRun(events: SessionEvent[]): StoredRunV1<undefined> {
+  return {
+    runId: "legacy-run",
+    commandFingerprint: "legacy-fingerprint",
+    sessionId: SESSION_ID,
+    acceptedAt: "2026-09-04T00:00:00.000Z",
+    input: "Earlier work",
+    events,
+    effectAdmissions: [],
+    status: "completed",
+    responseText: "Done earlier.",
+    phase: "executing",
+    compositionGenerationId: "legacy-generation",
+    configurationSnapshot: undefined,
+    previousEventCount: 0,
+  };
+}
+
+function createAuthority(
+  storage: SqliteLimitedMemoryStorage,
+): BotDurableAuthority<undefined> {
+  const hooks: BotDurableAuthorityHooks<undefined> = {
+    resolveAdmissionSnapshot: () => Promise.resolve(undefined),
+    bootstrapComposition: () => bootstrap(),
+    admittedSnapshot: () => Promise.resolve(undefined),
+    executeTurn: async (input) => {
+      let seq = input.previousEvents.length;
+      const events: SessionEvent[] = [];
+      const persist = async (
+        batch: Array<Omit<SessionEvent, "seq" | "timestamp">>,
+      ) => {
+        const stamped = batch.map(
+          (event) =>
+            ({
+              ...event,
+              seq: seq++,
+              timestamp: "2026-09-04T00:01:00.000Z",
+            }) as SessionEvent,
+        );
+        events.push(...stamped);
+        await input.persistSessionEvents(input.command.sessionId, stamped);
+      };
+
+      await persist([{ type: "turn/start", turn: 2 } as never]);
+      for (let step = 1; step <= STEPS; step += 1) {
+        await persist([
+          { type: "step/start", turn: 2, step } as never,
+          ...(step === 1
+            ? [
+                {
+                  type: "user/message",
+                  turn: 2,
+                  step,
+                  messageId: "message-2",
+                  text: input.command.text,
+                } as never,
+              ]
+            : []),
+          {
+            type: "model/request",
+            turn: 2,
+            step,
+            request: {
+              requestId: `request-${step}`,
+              provider: "fake",
+              model: "large-context",
+              system: "s".repeat(LARGE_REQUEST_BYTES),
+              messages: [{ role: "user", content: input.command.text }],
+              tools: [],
+            },
+          } as never,
+          {
+            type: "assistant/message",
+            turn: 2,
+            step,
+            requestId: `request-${step}`,
+            text: step === STEPS ? "All done." : "",
+            toolCalls: [],
+          } as never,
+          { type: "step/end", turn: 2, step, outcome: "completed" } as never,
+        ]);
+      }
+      await persist([
+        { type: "turn/end", turn: 2, outcome: "completed" } as never,
+      ]);
+      return { runId: input.command.runId, text: "All done.", events };
+    },
+    notification: () => undefined,
+    scheduledDeadlines: () => Promise.resolve([]),
+    scheduledWorkInFlight: () => false,
+    deferScheduledWork: () => Promise.resolve(),
+    settleScheduledWork: () => Promise.resolve(),
+  };
+  return new BotDurableAuthority<undefined>({
+    state: { storage } as unknown as DurableObjectState,
+    codec,
+    hooks,
+  });
+}
+
+describe("a long Turn on a legacy near-limit Session", () => {
+  test("migrates to bounded values and completes thirty large model steps", async () => {
+    const storage = new SqliteLimitedMemoryStorage();
+    const previous = legacyEvents();
+    const legacyBytes = new TextEncoder().encode(
+      JSON.stringify(previous),
+    ).byteLength;
+    expect(legacyBytes).toBeGreaterThan(1_900_000);
+    expect(legacyBytes).toBeLessThan(SQLITE_VALUE_LIMIT_BYTES);
+    // Seed through the backing map because these are values an older deploy
+    // already wrote. Every write made by the code under test is size-checked.
+    storage.values.set("latest-events", structuredClone(previous));
+    storage.values.set("run:legacy-run", structuredClone(legacyRun(previous)));
+
+    const completion = await createAuthority(storage).run({
+      userId: "user-1",
+      botId: "primary",
+      runId: "large-run",
+      sessionId: SESSION_ID,
+      acceptedAt: "2026-09-04T00:01:00.000Z",
+      text: "Keep going",
+    });
+
+    const stored = codec.require(storage.values.get("run:large-run"));
+    expect(storage.rejectedKeys).not.toContain("run:large-run");
+    expect(stored.failure ?? "").not.toContain("SQLITE_TOOBIG");
+    expect(completion.text).toBe("All done.");
+    expect(
+      completion.events.filter((event) => event.type === "model/request"),
+    ).toHaveLength(STEPS);
+    expect(storage.values.has("latest-events")).toBe(false);
+    expect(
+      [...storage.values.values()].every(
+        (value) =>
+          new TextEncoder().encode(JSON.stringify(value)).byteLength <=
+          SQLITE_VALUE_LIMIT_BYTES,
+      ),
+    ).toBe(true);
+  });
+});

package/src/storage-keys.ts

@@ -16,7 +16,15 @@ export const ACTIVE_RUN_KEY = "active-run";
  * working through a backlog of things the User has already replaced.
  */
 export const PENDING_RUN_KEY = "pending-run";
+/** Agent-lane Turns wait FIFO behind conversational work. */
+export const PENDING_AGENT_RUN_PREFIX = "pending-agent-run:";
+/** A Bot cannot accumulate an unbounded cross-Bot inbox. */
+export const MAX_PENDING_AGENT_RUNS_V1 = 32;
+/** Legacy pre-ADR-0033 Session value, read only for transparent migration. */
 export const LATEST_EVENTS_KEY = "latest-events";
+export const SESSION_EVENT_LOG_INDEX_PREFIX = "session-events:index:";
+export const SESSION_EVENT_LOG_PAGE_PREFIX = "session-events:page:";
+export const SESSION_EVENT_PAYLOAD_PREFIX = "session-events:payload:";
 export const IDENTITY_KEY = "identity";
 export const NOTIFICATION_PREFIX = "notification:";
 export const COMPOSITION_CURRENT_KEY = "composition:current";
@@ -80,6 +88,10 @@ export function runIndexKey(acceptedAt: string, runId: string): string {
   return `${RUN_INDEX_PREFIX}${acceptedAt}:${runId}`;
 }
 
+export function pendingAgentRunKey(acceptedAt: string, runId: string): string {
+  return `${PENDING_AGENT_RUN_PREFIX}${acceptedAt}:${runId}`;
+}
+
 export function compositionGenerationKey(generationId: string): string {
   return `${COMPOSITION_GENERATION_PREFIX}${generationId}`;
 }

package/src/turn-admission.test.ts

@@ -10,6 +10,7 @@ import {
   type BotTurnExecutionInput,
 } from "./authority.ts";
 import { MemoryStorage } from "./memory-storage.fixture.ts";
+import { SessionEventLog } from "./session-event-log.ts";
 import {
   botTurnCommandFingerprintV1,
   createStoredRunCodecV1,
@@ -36,6 +37,13 @@ const SUBAGENT_ORIGIN: StoredRunOriginV1 = {
   parentRunId: "run-parent",
 };
 
+const BOT_ORIGIN: StoredRunOriginV1 = {
+  kind: "bot",
+  fromBotId: "researcher",
+  fromBotName: "Researcher",
+  messageId: "agent-message-1",
+};
+
 const codec = createStoredRunCodecV1<undefined>({
   decodeRunId: (value) => value as string,
   decodeConfigurationSnapshot: () => undefined,
@@ -157,6 +165,22 @@ describe("the admission record names what produced the Turn", () => {
     expect(codec.require(structuredClone(decoded))).toEqual(decoded);
   });
 
+  test("round-trips an agent Turn and its sending Bot", () => {
+    const decoded = codec.require(
+      legacyRun({
+        admission: {
+          schemaVersion: 1,
+          turnType: "agent",
+          origin: BOT_ORIGIN,
+        },
+      }),
+    );
+
+    expect(decoded.admission?.origin).toEqual(BOT_ORIGIN);
+    expect(storedRunTurnTypeV1(decoded)).toBe("agent");
+    expect(codec.require(structuredClone(decoded))).toEqual(decoded);
+  });
+
   test("each origin kind has its own exact fields, and cannot borrow another's", () => {
     const withOrigin = (origin: unknown) =>
       legacyRun({
@@ -359,9 +383,14 @@ function command(runId: string, turnType?: TurnTypeV1) {
   };
 }
 
-function admittedEvent(storage: MemoryStorage, runId: string) {
+async function admittedEvent(storage: MemoryStorage, runId: string) {
   const run = storage.values.get(`run:${runId}`) as StoredRunV1<undefined>;
-  return run.events.find((event) => event.type === "turn/admission");
+  const events = await new SessionEventLog(storage).readRange(
+    run.sessionId,
+    run.eventRange!.startSeq,
+    run.eventRange!.endSeq,
+  );
+  return events.find((event) => event.type === "turn/admission");
 }
 
 describe("an admitted Turn re-mounts on its recorded turn type", () => {
@@ -389,11 +418,27 @@ describe("an admitted Turn re-mounts on its recorded turn type", () => {
       turnType: "automation",
     });
     expect(probe.observed[0]?.command.turnType).toBe("automation");
-    expect(admittedEvent(storage, "run-1")).toMatchObject({
+    expect(await admittedEvent(storage, "run-1")).toMatchObject({
       turnType: "automation",
     });
   });
 
+  test("an agent Turn defaults to the agent admission lane", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+
+    await probe.authority.run(command("run-agent", "agent"));
+
+    const stored = storage.values.get(
+      "run:run-agent",
+    ) as StoredRunV1<undefined>;
+    expect(stored.admission).toEqual({
+      schemaVersion: 1,
+      turnType: "agent",
+    });
+    expect(probe.observed[0]?.command.turnType).toBe("agent");
+  });
+
   test("after eviction the resumed run re-mounts on the recorded type", async () => {
     const storage = new MemoryStorage();
     const probe = createAuthority(storage);
@@ -407,17 +452,17 @@ describe("an admitted Turn re-mounts on its recorded turn type", () => {
       status: "running",
       phase: "executing",
       responseText: undefined,
-      events: [],
+      eventRange: { startSeq: 0, endSeq: 0 },
     });
     storage.values.set("active-run", "run-1");
     storage.values.set("identity", { userId: "user-1", botId: "primary" });
-    storage.values.set("latest-events", []);
+    await new SessionEventLog(storage).rewrite("user-1:primary", []);
 
     const resumed = createAuthority(storage);
     await resumed.authority.recoverActiveRun();
 
     expect(resumed.observed.at(-1)?.command.turnType).toBe("automation");
-    expect(admittedEvent(storage, "run-1")).toMatchObject({
+    expect(await admittedEvent(storage, "run-1")).toMatchObject({
       turnType: "automation",
     });
   });
@@ -433,17 +478,17 @@ describe("an admitted Turn re-mounts on its recorded turn type", () => {
       status: "running",
       phase: "executing",
       responseText: undefined,
-      events: [],
+      eventRange: { startSeq: 0, endSeq: 0 },
     });
     storage.values.set("active-run", "run-1");
     storage.values.set("identity", { userId: "user-1", botId: "primary" });
-    storage.values.set("latest-events", []);
+    await new SessionEventLog(storage).rewrite("user-1:primary", []);
 
     const resumed = createAuthority(storage);
     await resumed.authority.recoverActiveRun();
 
     expect(resumed.observed.at(-1)?.command.turnType).toBe("chat");
-    expect(admittedEvent(storage, "run-1")).toMatchObject({
+    expect(await admittedEvent(storage, "run-1")).toMatchObject({
       turnType: "chat",
     });
   });

package/src/turn-supersede.test.ts

@@ -15,6 +15,7 @@ import {
   type OwnedBotTurnCommand,
 } from "./authority.ts";
 import { MemoryStorage } from "./memory-storage.fixture.ts";
+import { SessionEventLog } from "./session-event-log.ts";
 import {
   BotTurnReconciliationRequiredError,
   BotTurnRecoveryRequiredError,
@@ -24,6 +25,10 @@ import {
   storedRunLaneV1,
   type StoredRunV1,
 } from "./run-records.ts";
+import {
+  MAX_PENDING_AGENT_RUNS_V1,
+  pendingAgentRunKey,
+} from "./storage-keys.ts";
 
 const codec = createStoredRunCodecV1<undefined>({
   decodeRunId: (value) => value as string,
@@ -92,8 +97,13 @@ interface Deferred<T> {
  * requests never reach a Durable Object in the same microtask, and the tests
  * that send two messages are describing two requests.
  */
-function admitted(): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, 0));
+async function admitted(): Promise<void> {
+  // Admission now also hashes any legacy event payloads it migrates. Let the
+  // Web Crypto promises and the Durable Object transaction both drain before
+  // inspecting the durable queue.
+  for (let turn = 0; turn < 8; turn += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
 }
 
 function deferred<T>(): Deferred<T> {
@@ -357,7 +367,9 @@ describe("a user message supersedes the running Turn", () => {
     probe.handle("run-2").finish();
     const result = await second;
 
-    const superseded = storedRun(storage, "run-1");
+    const superseded = await probe.authority.readRun("run-1");
+    expect(superseded).toBeDefined();
+    if (superseded === undefined) throw new Error("run-1 was not stored");
     expect(superseded.status).toBe("superseded");
     expect(superseded.supersededBy).toBe("run-2");
     expect(turnEndOf(superseded)).toMatchObject({
@@ -604,6 +616,150 @@ describe("a background admission never supersedes", () => {
   });
 });
 
+describe("the agent lane", () => {
+  test("queues behind the active Turn without superseding it", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+    const first = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+
+    const agent = probe.authority.run(
+      command("run-agent", "question", {
+        turnType: "agent",
+        origin: {
+          kind: "bot",
+          fromBotId: "researcher",
+          fromBotName: "Researcher",
+          messageId: "message-1",
+        },
+      }),
+    );
+    await admitted();
+    expect(probe.interrupts).toEqual([]);
+    expect(storedRun(storage, "run-agent")).toMatchObject({
+      phase: "queued",
+      admission: { turnType: "agent" },
+    });
+    expect(storedRunLaneV1(storedRun(storage, "run-agent"))).toBe("agent");
+
+    probe.handle("run-1").finish();
+    await first;
+    await probe.handle("run-agent").started;
+    probe.handle("run-agent").finish();
+    expect(await agent).toMatchObject({ text: "done: question" });
+  });
+
+  test("runs queued agent Turns FIFO", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+    const active = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+
+    const firstAgent = probe.authority.run(
+      command("run-agent-1", "first agent", { turnType: "agent" }),
+    );
+    await admitted();
+    const secondAgent = probe.authority.run(
+      command("run-agent-2", "second agent", { turnType: "agent" }),
+    );
+    await admitted();
+
+    probe.handle("run-1").finish();
+    await active;
+    await probe.handle("run-agent-1").started;
+    expect(probe.observed.map(({ command }) => command.runId)).toEqual([
+      "run-1",
+      "run-agent-1",
+    ]);
+    probe.handle("run-agent-1").finish();
+    await firstAgent;
+
+    await probe.handle("run-agent-2").started;
+    probe.handle("run-agent-2").finish();
+    await secondAgent;
+    expect(probe.observed.map(({ command }) => command.runId)).toEqual([
+      "run-1",
+      "run-agent-1",
+      "run-agent-2",
+    ]);
+  });
+
+  test("gives a queued User Turn priority over queued agent work", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+    const active = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+    const agent = probe.authority.run(
+      command("run-agent", "agent", { turnType: "agent" }),
+    );
+    await admitted();
+
+    const user = probe.authority.run(
+      command("run-user", "next message", {
+        lane: "user",
+        supersedes: { runId: "run-1" },
+      }),
+    );
+    await active;
+    await probe.handle("run-user").started;
+    expect(probe.observed.map(({ command }) => command.runId)).toEqual([
+      "run-1",
+      "run-user",
+    ]);
+    probe.handle("run-user").finish();
+    await user;
+
+    await probe.handle("run-agent").started;
+    probe.handle("run-agent").finish();
+    await agent;
+    expect(probe.observed.map(({ command }) => command.runId)).toEqual([
+      "run-1",
+      "run-user",
+      "run-agent",
+    ]);
+  });
+
+  test("refuses agent admission while the active Turn awaits reconciliation", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage, { parkOnRelease: () => true });
+    const active = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+    probe.handle("run-1").finish();
+    await active.catch(() => undefined);
+
+    await expect(
+      probe.authority.run(command("run-agent", "agent", { turnType: "agent" })),
+    ).rejects.toThrow(/cannot admit agent work.*requires reconciliation/);
+    expect(storage.values.has("run:run-agent")).toBe(false);
+  });
+
+  test("refuses admission when the Bot's bounded agent queue is full", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+    const first = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+    for (let index = 0; index < MAX_PENDING_AGENT_RUNS_V1; index += 1) {
+      const runId = `queued-${index}`;
+      storage.values.set(
+        pendingAgentRunKey(
+          new Date(Date.UTC(2026, 8, 3, 1, 0, index)).toISOString(),
+          runId,
+        ),
+        runId,
+      );
+    }
+
+    await expect(
+      probe.authority.run(
+        command("run-past-bound", "question", { turnType: "agent" }),
+      ),
+    ).rejects.toThrow(/agent queue is full \(32 Turns\)/);
+
+    probe.handle("run-1").finish();
+    await first;
+  });
+});
+
 describe("eviction between the two Turns", () => {
   /**
    * Exactly what the object holds at the moment between the superseded Turn
@@ -681,10 +837,7 @@ describe("a durable log left inside a Turn", () => {
     probe.handle("run-1").finish();
     await run;
 
-    const events = storage.values.get("latest-events") as Array<{
-      type: string;
-      turn?: number;
-    }>;
+    const events = await new SessionEventLog(storage).read("user-1:primary");
     // The orphaned Turn is closed, so the new one starts.
     expect(events[2]).toMatchObject({
       type: "turn/end",
@@ -738,7 +891,7 @@ describe("a durable log left inside a Turn", () => {
     probe.handle("run-1").finish();
     await run;
 
-    const events = storage.values.get("latest-events") as SessionEvent[];
+    const events = await new SessionEventLog(storage).read("user-1:primary");
     // Turn 1 is closed where it was abandoned, not after the Turns that
     // followed it, and the log is resequenced around the insertion.
     expect(