@vellumai/assistant 0.6.5 → 0.6.6

package/src/runtime/routes/playground/__tests__/seeded-conversations.test.ts

@@ -0,0 +1,309 @@
+import { describe, expect, test } from "bun:test";
+
+import type { Conversation } from "../../../../daemon/conversation.js";
+import type { RouteDefinition } from "../../../http-router.js";
+import type { PlaygroundRouteDeps } from "../deps.js";
+import { PLAYGROUND_TITLE_PREFIX } from "../seed-conversation.js";
+import { seededConversationsRouteDefinitions } from "../seeded-conversations.js";
+
+interface StubOpts {
+  enabled?: boolean;
+  listRows?: Array<{
+    id: string;
+    title: string;
+    messageCount: number;
+    createdAt: number;
+  }>;
+  getConversationById?: (id: string) => Promise<Conversation | undefined>;
+  deleteReturn?: boolean | ((id: string) => boolean);
+}
+
+interface Stub {
+  deps: PlaygroundRouteDeps;
+  listCalls: string[];
+  deleteCalls: string[];
+}
+
+function makeStub(opts: StubOpts = {}): Stub {
+  const listCalls: string[] = [];
+  const deleteCalls: string[] = [];
+  const deleteReturn = opts.deleteReturn ?? true;
+  const deps: PlaygroundRouteDeps = {
+    isPlaygroundEnabled: () => opts.enabled ?? true,
+    getConversationById: opts.getConversationById ?? (async () => undefined),
+    listConversationsByTitlePrefix: (prefix) => {
+      listCalls.push(prefix);
+      return opts.listRows ?? [];
+    },
+    deleteConversationById: (id) => {
+      deleteCalls.push(id);
+      return typeof deleteReturn === "function"
+        ? deleteReturn(id)
+        : deleteReturn;
+    },
+    createConversation: async () => ({ id: "conv-test" }),
+    addMessage: async () => ({ id: "msg-test" }),
+  };
+  return { deps, listCalls, deleteCalls };
+}
+
+function findRoute(
+  routes: RouteDefinition[],
+  method: string,
+  endpoint: string,
+): RouteDefinition {
+  const match = routes.find(
+    (r) => r.method === method && r.endpoint === endpoint,
+  );
+  if (!match) {
+    throw new Error(`Expected route ${method} ${endpoint} not found`);
+  }
+  return match;
+}
+
+// Minimal stand-in for the handler context — the seeded-conversation
+// handlers only read `params`, so we only populate that.
+function ctx(params: Record<string, string> = {}) {
+  return { params } as unknown as Parameters<RouteDefinition["handler"]>[0];
+}
+
+describe("seededConversationsRouteDefinitions — flag disabled", () => {
+  test("GET list returns 404 with playground_disabled code when the playground flag is off", async () => {
+    const { deps, listCalls } = makeStub({ enabled: false });
+    const routes = seededConversationsRouteDefinitions(deps);
+    const route = findRoute(routes, "GET", "playground/seeded-conversations");
+
+    const res = await route.handler(ctx());
+
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: string } };
+    // Distinct from `conversation_not_found` so the Swift client can
+    // surface the right toast text without sniffing the URL path.
+    expect(body.error.code).toBe("playground_disabled");
+    expect(listCalls).toEqual([]);
+  });
+
+  test("DELETE single returns 404 with playground_disabled code when the playground flag is off", async () => {
+    const { deps, deleteCalls } = makeStub({ enabled: false });
+    const routes = seededConversationsRouteDefinitions(deps);
+    const route = findRoute(
+      routes,
+      "DELETE",
+      "playground/seeded-conversations/:id",
+    );
+
+    const res = await route.handler(ctx({ id: "conv-1" }));
+
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("playground_disabled");
+    expect(deleteCalls).toEqual([]);
+  });
+
+  test("DELETE bulk returns 404 with playground_disabled code when the playground flag is off", async () => {
+    const { deps, listCalls, deleteCalls } = makeStub({ enabled: false });
+    const routes = seededConversationsRouteDefinitions(deps);
+    const route = findRoute(
+      routes,
+      "DELETE",
+      "playground/seeded-conversations",
+    );
+
+    const res = await route.handler(ctx());
+
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("playground_disabled");
+    expect(listCalls).toEqual([]);
+    expect(deleteCalls).toEqual([]);
+  });
+});
+
+describe("GET playground/seeded-conversations", () => {
+  test("forwards the prefix to the deps helper and returns the rows verbatim", async () => {
+    const rows = [
+      {
+        id: "conv-1",
+        title: `${PLAYGROUND_TITLE_PREFIX}First`,
+        messageCount: 4,
+        createdAt: 2000,
+      },
+      {
+        id: "conv-2",
+        title: `${PLAYGROUND_TITLE_PREFIX}Second`,
+        messageCount: 2,
+        createdAt: 1000,
+      },
+    ];
+    const { deps, listCalls } = makeStub({ listRows: rows });
+    const routes = seededConversationsRouteDefinitions(deps);
+    const route = findRoute(routes, "GET", "playground/seeded-conversations");
+
+    const res = await route.handler(ctx());
+    expect(res.status).toBe(200);
+
+    const body = (await res.json()) as {
+      conversations: typeof rows;
+    };
+    expect(body.conversations).toEqual(rows);
+    expect(listCalls).toEqual([PLAYGROUND_TITLE_PREFIX]);
+  });
+});
+
+describe("DELETE playground/seeded-conversations/:id", () => {
+  test("returns 403 when the conversation is not in the prefix-filtered set", async () => {
+    // The list call (authoritative prefix check) returns nothing for this id.
+    const { deps, deleteCalls } = makeStub({
+      listRows: [
+        {
+          id: "other-playground-id",
+          title: `${PLAYGROUND_TITLE_PREFIX}Kept`,
+          messageCount: 1,
+          createdAt: 1,
+        },
+      ],
+    });
+    const routes = seededConversationsRouteDefinitions(deps);
+    const route = findRoute(
+      routes,
+      "DELETE",
+      "playground/seeded-conversations/:id",
+    );
+
+    const res = await route.handler(ctx({ id: "non-playground-conv" }));
+
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as {
+      error: { code: string; message: string };
+    };
+    expect(body.error.code).toBe("FORBIDDEN");
+    expect(body.error.message).toBe("Not a playground conversation");
+    expect(deleteCalls).toEqual([]);
+  });
+
+  test("returns 200 and deletes when the id is a prefix-matching conversation", async () => {
+    const { deps, deleteCalls } = makeStub({
+      listRows: [
+        {
+          id: "conv-seeded",
+          title: `${PLAYGROUND_TITLE_PREFIX}Seeded`,
+          messageCount: 3,
+          createdAt: 5,
+        },
+      ],
+    });
+    const routes = seededConversationsRouteDefinitions(deps);
+    const route = findRoute(
+      routes,
+      "DELETE",
+      "playground/seeded-conversations/:id",
+    );
+
+    const res = await route.handler(ctx({ id: "conv-seeded" }));
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { deletedCount: number };
+    expect(body.deletedCount).toBe(1);
+    expect(deleteCalls).toEqual(["conv-seeded"]);
+  });
+
+  test("returns deletedCount: 0 when deleteConversationById reports a miss", async () => {
+    const { deps, deleteCalls } = makeStub({
+      listRows: [
+        {
+          id: "conv-seeded",
+          title: `${PLAYGROUND_TITLE_PREFIX}Seeded`,
+          messageCount: 0,
+          createdAt: 5,
+        },
+      ],
+      deleteReturn: false,
+    });
+    const routes = seededConversationsRouteDefinitions(deps);
+    const route = findRoute(
+      routes,
+      "DELETE",
+      "playground/seeded-conversations/:id",
+    );
+
+    const res = await route.handler(ctx({ id: "conv-seeded" }));
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { deletedCount: number };
+    expect(body.deletedCount).toBe(0);
+    expect(deleteCalls).toEqual(["conv-seeded"]);
+  });
+});
+
+describe("DELETE playground/seeded-conversations (bulk)", () => {
+  test("enumerates only prefix-matching rows and calls delete for each", async () => {
+    const rows = [
+      {
+        id: "conv-a",
+        title: `${PLAYGROUND_TITLE_PREFIX}A`,
+        messageCount: 0,
+        createdAt: 3,
+      },
+      {
+        id: "conv-b",
+        title: `${PLAYGROUND_TITLE_PREFIX}B`,
+        messageCount: 2,
+        createdAt: 2,
+      },
+      {
+        id: "conv-c",
+        title: `${PLAYGROUND_TITLE_PREFIX}C`,
+        messageCount: 5,
+        createdAt: 1,
+      },
+    ];
+    const { deps, listCalls, deleteCalls } = makeStub({ listRows: rows });
+    const routes = seededConversationsRouteDefinitions(deps);
+    const route = findRoute(
+      routes,
+      "DELETE",
+      "playground/seeded-conversations",
+    );
+
+    const res = await route.handler(ctx());
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { deletedCount: number };
+    expect(body.deletedCount).toBe(3);
+    expect(listCalls).toEqual([PLAYGROUND_TITLE_PREFIX]);
+    expect(deleteCalls).toEqual(["conv-a", "conv-b", "conv-c"]);
+  });
+
+  test("deletedCount reflects only rows where the underlying delete succeeded", async () => {
+    const rows = [
+      {
+        id: "conv-ok",
+        title: `${PLAYGROUND_TITLE_PREFIX}Ok`,
+        messageCount: 1,
+        createdAt: 2,
+      },
+      {
+        id: "conv-missing",
+        title: `${PLAYGROUND_TITLE_PREFIX}Missing`,
+        messageCount: 0,
+        createdAt: 1,
+      },
+    ];
+    const { deps, deleteCalls } = makeStub({
+      listRows: rows,
+      deleteReturn: (id) => id !== "conv-missing",
+    });
+    const routes = seededConversationsRouteDefinitions(deps);
+    const route = findRoute(
+      routes,
+      "DELETE",
+      "playground/seeded-conversations",
+    );
+
+    const res = await route.handler(ctx());
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { deletedCount: number };
+    expect(body.deletedCount).toBe(1);
+    expect(deleteCalls).toEqual(["conv-ok", "conv-missing"]);
+  });
+});

package/src/runtime/routes/playground/__tests__/state.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, mock, test } from "bun:test";
+
+mock.module("../../../../config/loader.js", () => ({
+  getConfig: () => ({
+    llm: {
+      default: {
+        contextWindow: {
+          enabled: true,
+          maxInputTokens: 200_000,
+          compactThreshold: 0.8,
+        },
+      },
+    },
+  }),
+}));
+
+// estimatePromptTokens has no external dependencies beyond its `messages`
+// argument, but we mock it so the assertions here do not depend on the
+// estimator's internal tuning.
+mock.module("../../../../context/token-estimator.js", () => ({
+  estimatePromptTokens: (messages: unknown[]): number => messages.length * 10,
+}));
+
+import type { Conversation } from "../../../../daemon/conversation.js";
+import type { PlaygroundRouteDeps } from "../deps.js";
+import { playgroundRouteDefinitions } from "../index.js";
+import { buildCompactionStateResponse } from "../state.js";
+
+function makeDeps(
+  overrides: Partial<PlaygroundRouteDeps> = {},
+): PlaygroundRouteDeps {
+  return {
+    getConversationById: async () => undefined,
+    isPlaygroundEnabled: () => true,
+    listConversationsByTitlePrefix: () => [],
+    deleteConversationById: () => false,
+    createConversation: async () => ({ id: "conv-test" }),
+    addMessage: async () => ({ id: "msg-test" }),
+    ...overrides,
+  };
+}
+
+interface FakeConversationOverrides {
+  messages?: unknown[];
+  contextCompactedMessageCount?: number;
+  contextCompactedAt?: number | null;
+  consecutiveCompactionFailures?: number;
+  compactionCircuitOpenUntil?: number | null;
+}
+
+function makeFakeConversation(
+  overrides: FakeConversationOverrides = {},
+): Conversation {
+  const messages = overrides.messages ?? [];
+  return {
+    getMessages: () => messages,
+    contextCompactedMessageCount: overrides.contextCompactedMessageCount ?? 0,
+    contextCompactedAt: overrides.contextCompactedAt ?? null,
+    consecutiveCompactionFailures: overrides.consecutiveCompactionFailures ?? 0,
+    compactionCircuitOpenUntil: overrides.compactionCircuitOpenUntil ?? null,
+  } as unknown as Conversation;
+}
+
+function findStateRoute() {
+  const routes = playgroundRouteDefinitions(makeDeps());
+  const route = routes.find(
+    (r) =>
+      r.endpoint === "conversations/:id/playground/compaction-state" &&
+      r.method === "GET",
+  );
+  if (!route) throw new Error("compaction-state route not registered");
+  return route;
+}
+
+async function invokeRoute(
+  deps: PlaygroundRouteDeps,
+  id = "conv-abc",
+): Promise<Response> {
+  const routes = playgroundRouteDefinitions(deps);
+  const route = routes.find(
+    (r) =>
+      r.endpoint === "conversations/:id/playground/compaction-state" &&
+      r.method === "GET",
+  );
+  if (!route) throw new Error("compaction-state route not registered");
+  // The handler only reads `params` from RouteContext — cast a minimal stub.
+  return Promise.resolve(
+    route.handler({
+      params: { id },
+    } as unknown as Parameters<typeof route.handler>[0]),
+  );
+}
+
+describe("GET conversations/:id/playground/compaction-state", () => {
+  test("registers the expected route definition", () => {
+    const route = findStateRoute();
+    expect(route.policyKey).toBe("conversations/playground/state");
+    expect(route.tags).toEqual(["playground"]);
+  });
+
+  test("returns 404 with playground_disabled code when the playground flag is disabled", async () => {
+    const deps = makeDeps({ isPlaygroundEnabled: () => false });
+    const res = await invokeRoute(deps);
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: string } };
+    // Distinct from `conversation_not_found` so the Swift client can
+    // surface the right toast text without sniffing the URL path.
+    expect(body.error.code).toBe("playground_disabled");
+  });
+
+  test("returns 404 with conversation_not_found code when the conversation does not exist", async () => {
+    const deps = makeDeps({
+      getConversationById: async () => undefined,
+    });
+    const res = await invokeRoute(deps, "missing-id");
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as {
+      error: { code: string; message: string };
+    };
+    expect(body.error.code).toBe("conversation_not_found");
+    expect(body.error.message).toContain("missing-id");
+  });
+
+  test("fresh conversation with no messages returns a baseline payload", async () => {
+    const conversation = makeFakeConversation();
+    const deps = makeDeps({
+      getConversationById: async () => conversation,
+    });
+    const res = await invokeRoute(deps);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as ReturnType<
+      typeof buildCompactionStateResponse
+    >;
+    expect(body.messageCount).toBe(0);
+    expect(body.estimatedInputTokens).toBe(0);
+    expect(body.maxInputTokens).toBe(200_000);
+    expect(body.compactThresholdRatio).toBe(0.8);
+    expect(body.thresholdTokens).toBe(160_000);
+    expect(body.contextCompactedMessageCount).toBe(0);
+    expect(body.contextCompactedAt).toBeNull();
+    expect(body.consecutiveCompactionFailures).toBe(0);
+    expect(body.compactionCircuitOpenUntil).toBeNull();
+    expect(body.isCircuitOpen).toBe(false);
+    expect(body.isCompactionEnabled).toBe(true);
+  });
+
+  test("open circuit breaker sets isCircuitOpen: true", async () => {
+    const future = Date.now() + 5_000;
+    const conversation = makeFakeConversation({
+      compactionCircuitOpenUntil: future,
+      consecutiveCompactionFailures: 3,
+    });
+    const deps = makeDeps({
+      getConversationById: async () => conversation,
+    });
+    const res = await invokeRoute(deps);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as ReturnType<
+      typeof buildCompactionStateResponse
+    >;
+    expect(body.compactionCircuitOpenUntil).toBe(future);
+    expect(body.consecutiveCompactionFailures).toBe(3);
+    expect(body.isCircuitOpen).toBe(true);
+  });
+
+  test("elapsed circuit-breaker deadline leaves isCircuitOpen: false", async () => {
+    const past = Date.now() - 1_000;
+    const conversation = makeFakeConversation({
+      compactionCircuitOpenUntil: past,
+    });
+    const deps = makeDeps({
+      getConversationById: async () => conversation,
+    });
+    const res = await invokeRoute(deps);
+    const body = (await res.json()) as ReturnType<
+      typeof buildCompactionStateResponse
+    >;
+    expect(body.compactionCircuitOpenUntil).toBe(past);
+    expect(body.isCircuitOpen).toBe(false);
+  });
+
+  test("full response shape matches the canonical CompactionStateResponse keys", async () => {
+    const conversation = makeFakeConversation({
+      messages: [{ role: "user" }, { role: "assistant" }],
+      contextCompactedMessageCount: 2,
+      contextCompactedAt: 1_700_000_000_000,
+      consecutiveCompactionFailures: 1,
+      compactionCircuitOpenUntil: null,
+    });
+    const deps = makeDeps({
+      getConversationById: async () => conversation,
+    });
+    const res = await invokeRoute(deps);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(Object.keys(body).sort()).toEqual(
+      [
+        "estimatedInputTokens",
+        "maxInputTokens",
+        "compactThresholdRatio",
+        "thresholdTokens",
+        "messageCount",
+        "contextCompactedMessageCount",
+        "contextCompactedAt",
+        "consecutiveCompactionFailures",
+        "compactionCircuitOpenUntil",
+        "isCircuitOpen",
+        "isCompactionEnabled",
+      ].sort(),
+    );
+    expect(body.messageCount).toBe(2);
+    expect(body.estimatedInputTokens).toBe(20);
+    expect(body.contextCompactedAt).toBe(1_700_000_000_000);
+    expect(body.contextCompactedMessageCount).toBe(2);
+  });
+});
+
+describe("buildCompactionStateResponse", () => {
+  test("is exported for reuse by PR 7 / PR 8 consolidations", () => {
+    const conversation = makeFakeConversation();
+    const snapshot = buildCompactionStateResponse(conversation);
+    expect(typeof snapshot.estimatedInputTokens).toBe("number");
+    expect(typeof snapshot.isCircuitOpen).toBe("boolean");
+  });
+});

package/src/runtime/routes/playground/conversation-not-found.ts

@@ -0,0 +1,29 @@
+/**
+ * Body code for "conversation lookup returned no row" 404s on
+ * conversation-scoped playground routes. Distinct from the generic
+ * `NOT_FOUND` code (and from `playground_disabled`, see `guard.ts`) so
+ * the Swift `CompactionPlaygroundClient` can pick `.notFound` over
+ * `.notAvailable` from the response body rather than from a URL-path
+ * heuristic. Without this distinction the `assertPlaygroundEnabled`
+ * guard's flag-off 404 (which fires *before* the conversation lookup on
+ * every conv-scoped route) would be indistinguishable from a real
+ * missing-conversation 404.
+ */
+export const CONVERSATION_NOT_FOUND_CODE = "conversation_not_found";
+
+/**
+ * Build a 404 response for a missing conversation on a playground route.
+ * Uses a distinguishing body `code` so the Swift client can route this
+ * to `.notFound` (rather than `.notAvailable`).
+ */
+export function conversationNotFoundResponse(conversationId: string): Response {
+  return Response.json(
+    {
+      error: {
+        code: CONVERSATION_NOT_FOUND_CODE,
+        message: `Conversation ${conversationId} not found`,
+      },
+    },
+    { status: 404 },
+  );
+}

package/src/runtime/routes/playground/deps.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared dependency contract for every `/v1/.../playground/*` route.
+ *
+ * Each playground route file accepts a `PlaygroundRouteDeps` and calls
+ * `assertPlaygroundEnabled(deps)` before doing any real work, so the route
+ * group is invisible in production regardless of UI gating.
+ *
+ * Later PRs in the compaction-playground plan (PR 6, PR 16, ...) extend this
+ * interface with additional capabilities. The scaffold keeps the surface
+ * intentionally minimal.
+ */
+
+import type { Conversation } from "../../../daemon/conversation.js";
+
+export interface PlaygroundRouteDeps {
+  /**
+   * Resolve a conversation by ID for conv-scoped playground routes
+   * (`forceCompact`, `injectFailures`, `resetCircuit`, `getState`). Async
+   * because production wiring may need to hydrate a `Conversation` from the
+   * DB on demand — freshly-seeded rows live only in the DB until the daemon
+   * loads them. Implementations must return `undefined` for IDs that do not
+   * exist in the DB at all so route handlers can preserve their 404 path.
+   */
+  readonly getConversationById: (
+    id: string,
+  ) => Promise<Conversation | undefined>;
+  readonly isPlaygroundEnabled: () => boolean;
+  /**
+   * List non-archived conversations whose title starts with `prefix`. Used by
+   * the seeded-conversation endpoints (GET list + bulk DELETE) to enumerate
+   * the playground-owned set without exposing every conversation.
+   */
+  readonly listConversationsByTitlePrefix: (prefix: string) => Array<{
+    id: string;
+    title: string;
+    messageCount: number;
+    createdAt: number;
+  }>;
+  /**
+   * Delete a conversation by ID. Returns `true` when a row was deleted, or
+   * `false` if no conversation with that ID exists. Kept narrow (no
+   * memory/vector cleanup surface) so route handlers don't accidentally
+   * skip the async cleanup the daemon handles elsewhere; the playground
+   * delete path is intentionally best-effort for freshly-seeded rows.
+   */
+  readonly deleteConversationById: (id: string) => boolean;
+  readonly createConversation: (title: string) => Promise<{ id: string }>;
+  readonly addMessage: (
+    conversationId: string,
+    role: "user" | "assistant",
+    contentJson: string,
+    options?: { skipIndexing?: boolean },
+  ) => Promise<{ id: string }>;
+  // Later PRs will extend this interface with additional capabilities.
+  // Keep this list minimal.
+}

package/src/runtime/routes/playground/force-compact.ts

@@ -0,0 +1,73 @@
+/**
+ * POST /v1/conversations/:id/playground/compact
+ *
+ * Force-compact a conversation (dev-only playground). Wraps
+ * `Conversation.forceCompact()` and returns the pre/post prompt-token
+ * estimates plus the summary metadata so the playground UI can display
+ * the delta.
+ *
+ * Guarded by `assertPlaygroundEnabled` — returns 404 when the
+ * `compaction-playground` feature flag is off.
+ */
+
+import { estimatePromptTokens } from "../../../context/token-estimator.js";
+import { httpError } from "../../http-errors.js";
+import type { RouteDefinition } from "../../http-router.js";
+import { conversationNotFoundResponse } from "./conversation-not-found.js";
+import { assertPlaygroundEnabled, type PlaygroundRouteDeps } from "./index.js";
+
+export function forceCompactRouteDefinitions(
+  deps: PlaygroundRouteDeps,
+): RouteDefinition[] {
+  return [
+    {
+      endpoint: "conversations/:id/playground/compact",
+      method: "POST",
+      policyKey: "conversations/playground/compact",
+      summary: "Force compaction on a conversation (dev-only playground)",
+      tags: ["playground"],
+      handler: async ({ params }) => {
+        const gate = assertPlaygroundEnabled(deps);
+        if (gate) return gate;
+
+        const conversation = await deps.getConversationById(params.id);
+        if (!conversation) {
+          return conversationNotFoundResponse(params.id);
+        }
+
+        // Per-conversation in-flight guard. `Conversation.processing` is set
+        // to `true` whenever an agent turn or a slash-`/compact` is mid-flight
+        // (see `conversation-routes.ts` and `Conversation.persistUserMessage`).
+        // If we ran a second `forceCompact()` against the same conversation
+        // while one was already in progress, we would race and double up
+        // `contextCompactedMessageCount`, emit duplicate `context_compacted`
+        // SSE events, and double-record usage. Easy to trigger by
+        // double-clicking the playground "Force Compact" button. Fail fast
+        // with 409 — the playground is a debug tool and clobbering legitimate
+        // in-flight processing is worse than a brief retryable error.
+        if (conversation.processing) {
+          return httpError(
+            "CONFLICT",
+            "Compaction already in progress for this conversation",
+            409,
+          );
+        }
+
+        const messagesBefore = conversation.getMessages();
+        const previousTokens = estimatePromptTokens(messagesBefore);
+        const result = await conversation.forceCompact();
+        const messagesAfter = conversation.getMessages();
+        const newTokens = estimatePromptTokens(messagesAfter);
+
+        return Response.json({
+          compacted: result.compacted,
+          previousTokens,
+          newTokens,
+          summaryText: result.summaryText ?? null,
+          messagesRemoved: result.compactedPersistedMessages ?? 0,
+          summaryFailed: result.summaryFailed ?? null,
+        });
+      },
+    },
+  ];
+}