@frockbot/plugin-shell 0.3.11 → 0.3.13

package/src/compaction-scheduler.test.ts

@@ -0,0 +1,96 @@
+// A compaction that outlives the Turn, and yields to the next one (ADR 0030).
+import { describe, expect, test } from "bun:test";
+import {
+  compactionInFlightV1,
+  compactionWorkV1,
+  whenCompactionSettledV1,
+  yieldCompactionWorkV1,
+} from "./compaction-scheduler.js";
+
+function stall(signal: AbortSignal): Promise<never> {
+  return new Promise((_resolve, reject) => {
+    signal.addEventListener("abort", () => reject(signal.reason), {
+      once: true,
+    });
+  });
+}
+
+/** A promise and the function that settles it, for ordering without timers. */
+function gate(): { promise: Promise<void>; open: () => void } {
+  let open = () => {};
+  const promise = new Promise<void>((resolve) => {
+    open = resolve;
+  });
+  return { promise, open };
+}
+
+describe("detached compaction", () => {
+  test("starting it does not wait for it", async () => {
+    const session = `session-${crypto.randomUUID()}`;
+    let finished = false;
+    const running = gate();
+    const started = Date.now();
+    compactionWorkV1(session).start(async (signal) => {
+      running.open();
+      await stall(signal).catch(() => {});
+      finished = true;
+    });
+    // The claim the defect got wrong: control is back immediately.
+    expect(Date.now() - started).toBeLessThan(50);
+    expect(finished).toBe(false);
+    expect(compactionInFlightV1(session)).toBe(true);
+    await running.promise;
+    await yieldCompactionWorkV1(session);
+    expect(finished).toBe(true);
+  });
+
+  test("a newly admitted Turn aborts it rather than queueing behind it", async () => {
+    const session = `session-${crypto.randomUUID()}`;
+    let reason: unknown;
+    const running = gate();
+    compactionWorkV1(session).start(async (signal) => {
+      running.open();
+      try {
+        await stall(signal);
+      } catch (error) {
+        reason = error;
+      }
+    });
+    await running.promise;
+    await yieldCompactionWorkV1(session);
+    expect(compactionInFlightV1(session)).toBe(false);
+    expect(String((reason as Error).message)).toContain("yielded");
+  });
+
+  test("a failure is nobody's problem, and never leaves work in flight", async () => {
+    const session = `session-${crypto.randomUUID()}`;
+    compactionWorkV1(session).start(async () => {
+      throw new Error("the summariser fell over");
+    });
+    await whenCompactionSettledV1(session);
+    expect(compactionInFlightV1(session)).toBe(false);
+  });
+
+  test("two compactions on one conversation never run beside each other", async () => {
+    const session = `session-${crypto.randomUUID()}`;
+    const order: string[] = [];
+    const release = gate();
+    compactionWorkV1(session).start(async () => {
+      order.push("first:start");
+      await release.promise;
+      order.push("first:end");
+    });
+    compactionWorkV1(session).start(async () => {
+      order.push("second:start");
+    });
+    release.open();
+    await whenCompactionSettledV1(session);
+    expect(order).toEqual(["first:start", "first:end", "second:start"]);
+  });
+
+  test("yielding costs nothing when no compaction is running", async () => {
+    await expect(
+      yieldCompactionWorkV1(`session-${crypto.randomUUID()}`),
+    ).resolves.toBeUndefined();
+  });
+});

package/src/compaction-scheduler.ts

@@ -0,0 +1,108 @@
+// Where a compaction actually runs, now that it no longer runs in the Turn.
+//
+// ADR 0030 always meant the summariser to cost a person nothing: it is
+// evaluated at Turn end, after `turn/end` is journaled, precisely so the Turn
+// they were waiting on is already over. The Turn-end hook honoured the *order*
+// and not the *waiting*: `agent/turn-stopping` is a serial hook the agent loop
+// awaits inside `#runTurn`'s `finally`, so `whenIdle` — and therefore the run's
+// terminal record, the `runs` broadcast, and the HTTP response — all sat behind
+// a 40-second model call. The client stayed busy the whole time.
+//
+// So the summariser is detached from the Turn here. The hook hands the work to
+// this scheduler and returns; the Turn ends, the run settles, the response goes
+// out, and the compaction carries on afterwards on the Composition the Turn
+// mounted, which is disposed when it finishes rather than when the Turn does.
+//
+// **It yields to admission.** The alternative — letting a compaction hold the
+// next Turn behind it — is the very latency this removes, one message later. So
+// the next admission aborts it and waits only for that abort to settle, which
+// keeps every write to the session log serialised behind exactly one owner. An
+// aborted compaction leaves an intent with no outcome, which is the case ADR
+// 0028 already covers: the next Turn end settles it as a failure and backoff
+// picks the range up again. Nothing is corrupted by losing one, and nobody
+// waits for one.
+//
+// Keyed by session id and held for the lifetime of the isolate, because that is
+// exactly the scope the work has: a Durable Object holds one conversation, and
+// work detached from one Turn has to be findable from the next.
+
+/** One conversation's detached compaction, at most one at a time. */
+class CompactionWork {
+  #controller: AbortController | undefined;
+  #settled: Promise<void> = Promise.resolve();
+
+  get inFlight(): boolean {
+    return this.#controller !== undefined;
+  }
+
+  /**
+   * Starts work that outlives the Turn. Returns as soon as the work has begun,
+   * never when it has finished — that is the whole point.
+   */
+  start(run: (signal: AbortSignal) => Promise<unknown>): void {
+    const controller = new AbortController();
+    const previous = this.#settled;
+    this.#controller = controller;
+    this.#settled = (async () => {
+      // Serialised rather than concurrent: two compactions writing to one
+      // session log is the one thing detaching them could get wrong.
+      await previous;
+      try {
+        // Aborted before it ever began — a Turn was admitted in the same tick.
+        if (!controller.signal.aborted) await run(controller.signal);
+      } catch {
+        // A compaction that fails is a conversation that carries on under ADR
+        // 0027's eviction. There is nobody to tell.
+      } finally {
+        if (this.#controller === controller) this.#controller = undefined;
+      }
+    })();
+  }
+
+  /** Waits for the work without hurrying it. For tests and for shutdown. */
+  whenSettled(): Promise<void> {
+    return this.#settled;
+  }
+
+  /**
+   * Hands the conversation back. Aborts anything in flight and waits for it to
+   * finish unwinding, so the next Turn is never writing to the log beside it.
+   */
+  async yieldToTurn(): Promise<void> {
+    this.#controller?.abort(
+      new Error("A new Turn was admitted, so the compaction yielded to it."),
+    );
+    await this.#settled;
+  }
+}
+
+const work = new Map<string, CompactionWork>();
+
+/** The detached compaction for one conversation, created on first use. */
+export function compactionWorkV1(sessionId: string): CompactionWork {
+  const existing = work.get(sessionId);
+  if (existing) return existing;
+  const created = new CompactionWork();
+  work.set(sessionId, created);
+  return created;
+}
+
+/**
+ * Called on the admission path, before a Turn reads the session log. Costs
+ * nothing when no compaction is in flight, and an abort when one is.
+ */
+export async function yieldCompactionWorkV1(sessionId: string): Promise<void> {
+  await work.get(sessionId)?.yieldToTurn();
+}
+
+/** Whether a conversation has a compaction still running. */
+export function compactionInFlightV1(sessionId: string): boolean {
+  return work.get(sessionId)?.inFlight ?? false;
+}
+
+/** Awaits a detached compaction without aborting it. Tests and shutdown only. */
+export async function whenCompactionSettledV1(
+  sessionId: string,
+): Promise<void> {
+  await work.get(sessionId)?.whenSettled();
+}

package/src/compaction-transcript.test.ts

@@ -0,0 +1,174 @@
+// Where the compaction marker sits in the transcript (ADR 0030).
+//
+// The marker is one system line, and the only thing it has to get right is
+// *where*: it says the Turns above it are what the model now carries a summary
+// of. Dated by when the summariser ran, it landed under the newest reply,
+// which says the opposite of what it means.
+import { describe, expect, test } from "bun:test";
+import type { SessionEvent } from "@frockbot/kernel-contracts";
+import { projectClientAnnouncementsV1 } from "./run-protocol.js";
+import { projectAnnouncements } from "./client/index.js";
+import { COMPACTED_ANNOUNCEMENT_TEXT_V1 } from "./compaction.js";
+import type { WebChatMessage } from "./shared.js";
+
+const at = (minute: number) =>
+  new Date(Date.UTC(2026, 0, 1, 0, minute)).toISOString();
+
+/** Three Turns, each a minute apart, and a compaction covering the first two. */
+function log(): SessionEvent[] {
+  const events: SessionEvent[] = [];
+  let seq = 0;
+  for (const turn of [1, 2, 3]) {
+    events.push(
+      { type: "turn/start", seq: seq++, timestamp: at(turn * 2), turn },
+      {
+        type: "turn/end",
+        seq: seq++,
+        timestamp: at(turn * 2 + 1),
+        turn,
+        outcome: "completed",
+      },
+    );
+  }
+  events.push({
+    type: "conversation/compacted",
+    seq: seq++,
+    // Written at the end of Turn 3, which is the Turn that crossed the
+    // threshold — and nowhere near the range it covers.
+    timestamp: at(7),
+    effectId: "compaction-1",
+    fromTurn: 1,
+    throughTurn: 2,
+    summary: "## Summary\nprivate to the model",
+    identifiers: [],
+    provider: "ollama-cloud",
+    model: "kimi-k2",
+  });
+  return events;
+}
+
+function message(
+  id: string,
+  role: WebChatMessage["role"],
+  timestamp?: string,
+): WebChatMessage {
+  return {
+    id,
+    runId: id.split(":")[0]!,
+    role,
+    text: id,
+    ...(timestamp ? { at: timestamp } : {}),
+    status: "completed",
+    tools: [],
+    sends: [],
+  };
+}
+
+/** The thread as `projectDurableRuns` leaves it: only user lines are dated. */
+function thread(turns: readonly number[]): WebChatMessage[] {
+  return turns.flatMap((turn) => [
+    message(`run-${turn}:user`, "user", at(turn * 2)),
+    message(`run-${turn}:assistant`, "assistant"),
+  ]);
+}
+
+describe("the compaction marker sits where the summary ends", () => {
+  test("is dated by the end of the range it covers, not by when it was written", () => {
+    const announcements = projectClientAnnouncementsV1(
+      log().filter((event) => event.type === "conversation/compacted"),
+      log(),
+    );
+    expect(announcements).toEqual([
+      {
+        type: "conversation/compacted",
+        announcementId: "compaction-6",
+        // `turn/end` for Turn 2, not the compaction's own timestamp of 00:07.
+        at: at(5),
+        throughTurn: 2,
+      },
+    ]);
+    // Without the session log there is nothing to anchor to, and the old
+    // behaviour stands rather than a wrong claim being invented.
+    expect(
+      projectClientAnnouncementsV1(
+        log().filter((event) => event.type === "conversation/compacted"),
+      )[0]?.at,
+    ).toBe(at(7));
+  });
+
+  test("lands between the last compacted Turn and the first verbatim one, and stays there", () => {
+    const announcements = projectClientAnnouncementsV1(
+      log().filter((event) => event.type === "conversation/compacted"),
+      log(),
+    );
+    const messages = thread([1, 2, 3]);
+    projectAnnouncements(messages, announcements);
+    expect(messages.map((entry) => entry.id)).toEqual([
+      "run-1:user",
+      "run-1:assistant",
+      "run-2:user",
+      "run-2:assistant",
+      "compaction-6",
+      "run-3:user",
+      "run-3:assistant",
+    ]);
+    expect(messages[4]?.text).toBe(COMPACTED_ANNOUNCEMENT_TEXT_V1);
+    expect(messages[4]?.role).toBe("system");
+
+    // A newer Turn arrives and the marker does not follow it down.
+    messages.push(
+      message("run-4:user", "user", at(8)),
+      message("run-4:assistant", "assistant"),
+    );
+    projectAnnouncements(messages, announcements);
+    expect(messages.map((entry) => entry.id)).toEqual([
+      "run-1:user",
+      "run-1:assistant",
+      "run-2:user",
+      "run-2:assistant",
+      "compaction-6",
+      "run-3:user",
+      "run-3:assistant",
+      "run-4:user",
+      "run-4:assistant",
+    ]);
+  });
+
+  test("sits at the top of what remains when the covered Turns have scrolled away", () => {
+    const announcements = projectClientAnnouncementsV1(
+      log().filter((event) => event.type === "conversation/compacted"),
+      log(),
+    );
+    const messages = thread([3]);
+    projectAnnouncements(messages, announcements);
+    expect(messages.map((entry) => entry.id)).toEqual([
+      "compaction-6",
+      "run-3:user",
+      "run-3:assistant",
+    ]);
+  });
+
+  test("a rename still sorts among the Turns it happened between", () => {
+    const renamed = projectClientAnnouncementsV1([
+      {
+        type: "bot/renamed",
+        seq: 3,
+        timestamp: at(5),
+        from: "Housework",
+        to: "Atlas",
+        namedBy: "bot",
+      },
+    ]);
+    const messages = thread([1, 2, 3]);
+    projectAnnouncements(messages, renamed);
+    expect(messages.map((entry) => entry.id)).toEqual([
+      "run-1:user",
+      "run-1:assistant",
+      "run-2:user",
+      "run-2:assistant",
+      "announcement-3",
+      "run-3:user",
+      "run-3:assistant",
+    ]);
+  });
+});