@vellumai/assistant 0.6.5 → 0.6.6

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

@@ -0,0 +1,37 @@
+import type { PlaygroundRouteDeps } from "./deps.js";
+
+/**
+ * Body code for flag-off playground 404s. Distinct from the generic
+ * `NOT_FOUND` code so the Swift `CompactionPlaygroundClient` can route
+ * these to `.notAvailable` (toast: "Playground endpoints disabled")
+ * rather than `.notFound` (toast: "Conversation not found"). The two
+ * cases are otherwise indistinguishable on conv-scoped routes because
+ * `assertPlaygroundEnabled` runs *before* the conversation lookup, so a
+ * URL-path heuristic on the client misclassifies flag-off as missing-
+ * conversation. See `conversation-not-found.ts` for the matching code on
+ * the other branch.
+ */
+export const PLAYGROUND_DISABLED_CODE = "playground_disabled";
+
+/**
+ * Defense-in-depth guard every playground route calls first. Returns a 404
+ * Response when the `compaction-playground` feature flag is disabled so the
+ * entire /playground/* surface is invisible in production regardless of UI
+ * gating.
+ */
+export function assertPlaygroundEnabled(
+  deps: PlaygroundRouteDeps,
+): Response | null {
+  if (!deps.isPlaygroundEnabled()) {
+    return Response.json(
+      {
+        error: {
+          code: PLAYGROUND_DISABLED_CODE,
+          message: "Compaction playground is not enabled",
+        },
+      },
+      { status: 404 },
+    );
+  }
+  return null;
+}

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

@@ -0,0 +1,28 @@
+import type { RouteDefinition } from "../../http-router.js";
+import type { PlaygroundRouteDeps } from "./deps.js";
+import { forceCompactRouteDefinitions } from "./force-compact.js";
+import { injectFailuresRouteDefinitions } from "./inject-failures.js";
+import { resetCircuitRouteDefinitions } from "./reset-circuit.js";
+import { seedConversationRouteDefinitions } from "./seed-conversation.js";
+import { seededConversationsRouteDefinitions } from "./seeded-conversations.js";
+import { stateRouteDefinitions } from "./state.js";
+
+export type { PlaygroundRouteDeps };
+export { assertPlaygroundEnabled } from "./guard.js";
+
+export function playgroundRouteDefinitions(
+  deps: PlaygroundRouteDeps,
+): RouteDefinition[] {
+  // Each playground route file exports its own `*RouteDefinitions(deps)`
+  // factory; this aggregator spreads the arrays together. Later PRs in the
+  // plan append more imports here — keeping it purely additive minimizes
+  // conflicts across concurrent playground PRs.
+  return [
+    ...forceCompactRouteDefinitions(deps),
+    ...injectFailuresRouteDefinitions(deps),
+    ...resetCircuitRouteDefinitions(deps),
+    ...seedConversationRouteDefinitions(deps),
+    ...seededConversationsRouteDefinitions(deps),
+    ...stateRouteDefinitions(deps),
+  ];
+}

package/src/runtime/routes/playground/inject-failures.ts

@@ -0,0 +1,159 @@
+/**
+ * POST /v1/conversations/:id/playground/inject-compaction-failures
+ * directly mutates the compaction circuit-breaker state on a conversation.
+ *
+ * This is a dev-only playground endpoint gated by the
+ * `compaction-playground` feature flag. It lets integration tests and the
+ * macOS playground UI drive the circuit breaker into interesting states
+ * without having to wait for real consecutive summary-LLM failures.
+ *
+ * When `circuitOpenForMs` is set to a positive number, the endpoint emits a
+ * `compaction_circuit_open` event with reason `3_consecutive_failures`
+ * (matching the event shape produced by `trackCompactionOutcome` in
+ * `conversation-agent-loop.ts`). Passing `circuitOpenForMs: 0` clears the
+ * open-until timestamp and emits `compaction_circuit_closed`, mirroring the
+ * transition event the daemon emits on the open → closed edge.
+ */
+
+import { z } from "zod";
+
+import { getConfig } from "../../../config/loader.js";
+import { estimatePromptTokens } from "../../../context/token-estimator.js";
+import type { Conversation } from "../../../daemon/conversation.js";
+import { httpError } from "../../http-errors.js";
+import type { RouteDefinition } from "../../http-router.js";
+import { conversationNotFoundResponse } from "./conversation-not-found.js";
+import type { PlaygroundRouteDeps } from "./deps.js";
+import { assertPlaygroundEnabled } from "./guard.js";
+
+const InjectBodySchema = z.object({
+  consecutiveFailures: z.number().int().min(0).max(10).optional(),
+  circuitOpenForMs: z
+    .number()
+    .int()
+    .min(0)
+    .max(24 * 60 * 60 * 1000)
+    .optional(),
+});
+
+export function injectFailuresRouteDefinitions(
+  deps: PlaygroundRouteDeps,
+): RouteDefinition[] {
+  return [
+    {
+      endpoint: "conversations/:id/playground/inject-compaction-failures",
+      method: "POST",
+      policyKey: "conversations/playground/inject-failures",
+      summary:
+        "Directly mutate compaction circuit-breaker state (dev-only playground)",
+      tags: ["playground"],
+      requestBody: InjectBodySchema,
+      handler: async ({ req, params }) => {
+        const gate = assertPlaygroundEnabled(deps);
+        if (gate) return gate;
+
+        const conversation = await deps.getConversationById(params.id);
+        if (!conversation) {
+          return conversationNotFoundResponse(params.id);
+        }
+
+        let rawBody: unknown = {};
+        try {
+          const contentLength = req.headers.get("content-length");
+          if (contentLength !== "0" && req.body !== null) {
+            rawBody = await req.json();
+          }
+        } catch {
+          return httpError("BAD_REQUEST", "Invalid JSON body", 400);
+        }
+
+        const parsed = InjectBodySchema.safeParse(rawBody ?? {});
+        if (!parsed.success) {
+          return httpError("BAD_REQUEST", parsed.error.message, 400);
+        }
+        const { consecutiveFailures, circuitOpenForMs } = parsed.data;
+
+        if (consecutiveFailures !== undefined) {
+          conversation.consecutiveCompactionFailures = consecutiveFailures;
+        }
+
+        if (circuitOpenForMs !== undefined) {
+          if (circuitOpenForMs === 0) {
+            // Mirror `trackCompactionOutcome()` (and `reset-circuit.ts`) —
+            // emit `compaction_circuit_closed` only on the open→closed
+            // transition so clients don't receive a redundant close event
+            // when the breaker was already closed.
+            if (conversation.compactionCircuitOpenUntil !== null) {
+              conversation.compactionCircuitOpenUntil = null;
+              conversation.sendToClient({
+                type: "compaction_circuit_closed",
+                conversationId: conversation.conversationId,
+              });
+            }
+          } else {
+            const openUntil = Date.now() + circuitOpenForMs;
+            conversation.compactionCircuitOpenUntil = openUntil;
+            conversation.sendToClient({
+              type: "compaction_circuit_open",
+              conversationId: conversation.conversationId,
+              reason: "3_consecutive_failures",
+              openUntil,
+            });
+          }
+        }
+
+        return Response.json(buildCompactionState(conversation));
+      },
+    },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Local state-builder — identical in shape to `buildCompactionStateResponse`
+// in `state.ts` and the local copy in `reset-circuit.ts`. A follow-up cleanup
+// can consolidate these onto `state.ts`'s exported helper.
+// ---------------------------------------------------------------------------
+
+export interface CompactionStateResponse {
+  estimatedInputTokens: number;
+  maxInputTokens: number;
+  compactThresholdRatio: number;
+  thresholdTokens: number;
+  messageCount: number;
+  contextCompactedMessageCount: number;
+  contextCompactedAt: number | null;
+  consecutiveCompactionFailures: number;
+  compactionCircuitOpenUntil: number | null;
+  isCircuitOpen: boolean;
+  isCompactionEnabled: boolean;
+}
+
+function buildCompactionState(
+  conversation: Conversation,
+): CompactionStateResponse {
+  const ctxConfig = getConfig().llm.default.contextWindow;
+  const maxInputTokens = ctxConfig.maxInputTokens;
+  const compactThresholdRatio = ctxConfig.compactThreshold;
+  const isCompactionEnabled = ctxConfig.enabled;
+  const thresholdTokens = Math.floor(maxInputTokens * compactThresholdRatio);
+
+  const messages = conversation.getMessages();
+  const estimatedInputTokens = estimatePromptTokens(messages);
+  const circuitOpenUntil = conversation.compactionCircuitOpenUntil;
+  const isCircuitOpen =
+    circuitOpenUntil !== null && Date.now() < circuitOpenUntil;
+
+  return {
+    estimatedInputTokens,
+    maxInputTokens,
+    compactThresholdRatio,
+    thresholdTokens,
+    messageCount: messages.length,
+    contextCompactedMessageCount: conversation.contextCompactedMessageCount,
+    contextCompactedAt: conversation.contextCompactedAt,
+    consecutiveCompactionFailures: conversation.consecutiveCompactionFailures,
+    compactionCircuitOpenUntil: circuitOpenUntil,
+    isCircuitOpen,
+    isCompactionEnabled,
+  };
+}

package/src/runtime/routes/playground/reset-circuit.ts

@@ -0,0 +1,115 @@
+/**
+ * POST /v1/conversations/:id/playground/reset-compaction-circuit
+ *
+ * Dev-only playground endpoint that clears the compaction circuit-breaker
+ * state on a live conversation. Intended for reproducing flows that normally
+ * require three real summary-LLM failures to trigger — without this hatch,
+ * exercising the "auto-compaction paused" banner requires bespoke fault
+ * injection.
+ *
+ * Behavior:
+ *   - `consecutiveCompactionFailures` is always zeroed.
+ *   - `compactionCircuitOpenUntil` is cleared to null only when it was set;
+ *     the `compaction_circuit_closed` event is emitted on the open→closed
+ *     transition so the Swift banner dismisses immediately, mirroring the
+ *     behavior of a successful compaction in `trackCompactionOutcome()`.
+ *     Calling this endpoint while the breaker is already closed is a no-op
+ *     on the event channel — it never emits a redundant close event.
+ *
+ * Guarded by `assertPlaygroundEnabled()` — the route 404s when the
+ * `compaction-playground` feature flag is disabled, so the entire surface
+ * is invisible in production.
+ */
+
+import { getConfig } from "../../../config/loader.js";
+import { estimatePromptTokens } from "../../../context/token-estimator.js";
+import type { Conversation } from "../../../daemon/conversation.js";
+import type { RouteDefinition } from "../../http-router.js";
+// Import directly from the source modules (not ./index.js) — index.ts imports
+// this file's `resetCircuitRouteDefinitions`, so pulling its re-exports back
+// through the barrel would create a cycle.
+import { conversationNotFoundResponse } from "./conversation-not-found.js";
+import type { PlaygroundRouteDeps } from "./deps.js";
+import { assertPlaygroundEnabled } from "./guard.js";
+
+export function resetCircuitRouteDefinitions(
+  deps: PlaygroundRouteDeps,
+): RouteDefinition[] {
+  return [
+    {
+      endpoint: "conversations/:id/playground/reset-compaction-circuit",
+      method: "POST",
+      policyKey: "conversations/playground/reset-circuit",
+      summary: "Clear compaction circuit-breaker state (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);
+        }
+
+        conversation.consecutiveCompactionFailures = 0;
+        if (conversation.compactionCircuitOpenUntil !== null) {
+          conversation.compactionCircuitOpenUntil = null;
+          // Mirror `trackCompactionOutcome()` — emit only on the open→closed
+          // transition so clients don't receive a redundant close event when
+          // the breaker was already closed.
+          conversation.sendToClient({
+            type: "compaction_circuit_closed",
+            conversationId: conversation.conversationId,
+          });
+        }
+
+        return Response.json(buildCompactionState(conversation));
+      },
+    },
+  ];
+}
+
+/**
+ * Local state-builder with the same shape as the (future) shared
+ * `CompactionStateResponse`. Sibling PRs (7, 9) carry near-identical copies;
+ * PR 9 extracts a consolidated version and this local copy can be deleted at
+ * that cleanup step.
+ */
+function buildCompactionState(conversation: Conversation): {
+  estimatedInputTokens: number;
+  maxInputTokens: number;
+  compactThresholdRatio: number;
+  thresholdTokens: number;
+  messageCount: number;
+  contextCompactedMessageCount: number;
+  contextCompactedAt: number | null;
+  consecutiveCompactionFailures: number;
+  compactionCircuitOpenUntil: number | null;
+  isCircuitOpen: boolean;
+  isCompactionEnabled: boolean;
+} {
+  const config = getConfig();
+  const contextWindow = config.llm.default.contextWindow;
+  const messages = conversation.getMessages();
+  const estimatedInputTokens = estimatePromptTokens(messages);
+  const maxInputTokens = contextWindow.maxInputTokens;
+  const compactThresholdRatio = contextWindow.compactThreshold;
+  const thresholdTokens = Math.floor(maxInputTokens * compactThresholdRatio);
+  const isCircuitOpen =
+    conversation.compactionCircuitOpenUntil !== null &&
+    Date.now() < conversation.compactionCircuitOpenUntil;
+
+  return {
+    estimatedInputTokens,
+    maxInputTokens,
+    compactThresholdRatio,
+    thresholdTokens,
+    messageCount: messages.length,
+    contextCompactedMessageCount: conversation.contextCompactedMessageCount,
+    contextCompactedAt: conversation.contextCompactedAt,
+    consecutiveCompactionFailures: conversation.consecutiveCompactionFailures,
+    compactionCircuitOpenUntil: conversation.compactionCircuitOpenUntil,
+    isCircuitOpen,
+    isCompactionEnabled: contextWindow.enabled,
+  };
+}

package/src/runtime/routes/playground/seed-conversation.ts

@@ -0,0 +1,139 @@
+/**
+ * POST /v1/playground/seed-conversation
+ *
+ * Creates a synthetic conversation for compaction testing. Inserts N
+ * user/assistant message pairs of roughly `avgTokensPerTurn` tokens each and
+ * returns the new conversation id plus an estimated prompt-token count.
+ *
+ * Seeded conversations are prefixed with `[Playground] ` so other playground
+ * endpoints (e.g. seeded-conversations list/delete) can filter by prefix.
+ */
+
+import { z } from "zod";
+
+import { estimatePromptTokens } from "../../../context/token-estimator.js";
+import type { Message } from "../../../providers/types.js";
+import { httpError } from "../../http-errors.js";
+import type { RouteDefinition } from "../../http-router.js";
+import { assertPlaygroundEnabled, type PlaygroundRouteDeps } from "./index.js";
+
+/**
+ * Title prefix applied to every seeded-playground conversation. Exported so
+ * sibling playground endpoints (list/delete) can share the exact string
+ * rather than duplicating a literal.
+ */
+export const PLAYGROUND_TITLE_PREFIX = "[Playground] ";
+
+const SeedBodySchema = z.object({
+  turns: z.number().int().positive().max(500),
+  avgTokensPerTurn: z
+    .number()
+    .int()
+    .positive()
+    .max(5000)
+    .optional()
+    .default(500),
+  title: z.string().trim().max(120).optional(),
+});
+
+const LOREM_BASE =
+  "Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. ";
+
+export function seedConversationRouteDefinitions(
+  deps: PlaygroundRouteDeps,
+): RouteDefinition[] {
+  return [
+    {
+      endpoint: "playground/seed-conversation",
+      method: "POST",
+      policyKey: "playground/seed-conversation",
+      summary: "Create a synthetic seeded conversation for compaction testing",
+      tags: ["playground"],
+      requestBody: SeedBodySchema,
+      handler: async ({ req }) => {
+        const gate = assertPlaygroundEnabled(deps);
+        if (gate) return gate;
+
+        let rawBody: unknown;
+        try {
+          rawBody = await req.json();
+        } catch {
+          return httpError("BAD_REQUEST", "Invalid JSON body", 400);
+        }
+
+        const parsed = SeedBodySchema.safeParse(rawBody);
+        if (!parsed.success) {
+          return httpError("BAD_REQUEST", parsed.error.message, 400);
+        }
+        const { turns, avgTokensPerTurn, title } = parsed.data;
+
+        // Derive effective title: strip an accidental prefix first so a
+        // caller passing "[Playground] foo" doesn't end up with
+        // "[Playground] [Playground] foo".
+        const userSuppliedTitle =
+          title && title.length > 0
+            ? title
+            : new Date().toISOString().slice(0, 19);
+        const withoutPrefix = userSuppliedTitle.startsWith(
+          PLAYGROUND_TITLE_PREFIX,
+        )
+          ? userSuppliedTitle.slice(PLAYGROUND_TITLE_PREFIX.length)
+          : userSuppliedTitle;
+        const effectiveTitle = PLAYGROUND_TITLE_PREFIX + withoutPrefix;
+
+        const { id: conversationId } =
+          await deps.createConversation(effectiveTitle);
+
+        // Generate lorem-ipsum-style text. ~4 chars/token is the rough
+        // approximation the rest of the daemon uses. Paragraph is repeated
+        // and sliced to the target byte count, and a "Turn N" prefix keeps
+        // each message unique so downstream search/compaction doesn't
+        // collapse them.
+        const charsPerMessage = avgTokensPerTurn * 4;
+
+        const messages: Array<{ role: "user" | "assistant"; text: string }> =
+          [];
+        for (let i = 0; i < turns; i++) {
+          const userBase = `Turn ${i + 1} user message: ` + LOREM_BASE;
+          const userText = userBase
+            .repeat(Math.ceil(charsPerMessage / userBase.length))
+            .slice(0, charsPerMessage);
+          const asstBase = `Turn ${i + 1} assistant response: ` + LOREM_BASE;
+          const asstText = asstBase
+            .repeat(Math.ceil(charsPerMessage / asstBase.length))
+            .slice(0, charsPerMessage);
+          messages.push({ role: "user", text: userText });
+          messages.push({ role: "assistant", text: asstText });
+        }
+
+        for (const msg of messages) {
+          const contentJson = JSON.stringify([
+            { type: "text", text: msg.text },
+          ]);
+          // Skip memory/vector indexing for seeded synthetic messages — the
+          // lorem-ipsum content has no semantic value and would otherwise
+          // spam the embedding pipeline (2 embeddings per turn × up to 500
+          // turns) and pollute the vector store.
+          await deps.addMessage(conversationId, msg.role, contentJson, {
+            skipIndexing: true,
+          });
+        }
+
+        // Reconstruct the in-memory Message[] shape estimatePromptTokens
+        // expects so the returned estimate matches what compaction will
+        // see once the conversation is loaded.
+        const estimatorMessages: Message[] = messages.map((m) => ({
+          role: m.role,
+          content: [{ type: "text", text: m.text }],
+        }));
+        const estimatedTokens = estimatePromptTokens(estimatorMessages);
+
+        return Response.json({
+          conversationId,
+          messagesInserted: messages.length,
+          estimatedTokens,
+        });
+      },
+    },
+  ];
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Playground-only list/delete endpoints for conversations seeded by the
+ * seed-conversation route. Prefix-gated on the title (every seeded
+ * conversation is titled `[Playground] ...`) so a flag-on caller cannot use
+ * these routes to list or delete unrelated conversations.
+ */
+
+import { httpError } from "../../http-errors.js";
+import type { RouteDefinition } from "../../http-router.js";
+import { assertPlaygroundEnabled, type PlaygroundRouteDeps } from "./index.js";
+import { PLAYGROUND_TITLE_PREFIX } from "./seed-conversation.js";
+
+export function seededConversationsRouteDefinitions(
+  deps: PlaygroundRouteDeps,
+): RouteDefinition[] {
+  return [
+    {
+      endpoint: "playground/seeded-conversations",
+      method: "GET",
+      policyKey: "playground/seeded-conversations/list",
+      summary: "List conversations created by the seed-conversation endpoint",
+      tags: ["playground"],
+      handler: async () => {
+        const gate = assertPlaygroundEnabled(deps);
+        if (gate) return gate;
+        const conversations = deps.listConversationsByTitlePrefix(
+          PLAYGROUND_TITLE_PREFIX,
+        );
+        return Response.json({ conversations });
+      },
+    },
+    {
+      endpoint: "playground/seeded-conversations/:id",
+      method: "DELETE",
+      policyKey: "playground/seeded-conversations/delete-one",
+      summary: "Delete a single seeded conversation (prefix-gated)",
+      tags: ["playground"],
+      handler: async ({ params }) => {
+        const gate = assertPlaygroundEnabled(deps);
+        if (gate) return gate;
+
+        // The in-memory `Conversation` object does not carry the DB title,
+        // and the seeded row may not be loaded into memory at all. Use the
+        // prefix-filtered DB listing as the authoritative membership check
+        // so we reject attempts to delete arbitrary conversations via this
+        // endpoint even when the flag is on.
+        const seeded = deps
+          .listConversationsByTitlePrefix(PLAYGROUND_TITLE_PREFIX)
+          .find((c) => c.id === params.id);
+        if (!seeded) {
+          return httpError("FORBIDDEN", "Not a playground conversation", 403);
+        }
+
+        const deleted = deps.deleteConversationById(params.id);
+        return Response.json({ deletedCount: deleted ? 1 : 0 });
+      },
+    },
+    {
+      endpoint: "playground/seeded-conversations",
+      method: "DELETE",
+      policyKey: "playground/seeded-conversations/delete-all",
+      summary: "Delete every seeded playground conversation (prefix-gated)",
+      tags: ["playground"],
+      handler: async () => {
+        const gate = assertPlaygroundEnabled(deps);
+        if (gate) return gate;
+        const candidates = deps.listConversationsByTitlePrefix(
+          PLAYGROUND_TITLE_PREFIX,
+        );
+        let deletedCount = 0;
+        for (const c of candidates) {
+          if (deps.deleteConversationById(c.id)) deletedCount++;
+        }
+        return Response.json({ deletedCount });
+      },
+    },
+  ];
+}

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

@@ -0,0 +1,78 @@
+/**
+ * GET /v1/conversations/:id/playground/compaction-state
+ *
+ * Read-only view of compaction-relevant state for a conversation. Returns the
+ * token estimate, the configured maxInputTokens / compactThreshold, the
+ * derived threshold token count, current message count, compaction-progress
+ * counters, and circuit-breaker status.
+ *
+ * The endpoint is gated by the `compaction-playground` feature flag via the
+ * shared `assertPlaygroundEnabled` guard — when disabled the whole surface is
+ * invisible in production.
+ */
+
+import { getConfig } from "../../../config/loader.js";
+import { estimatePromptTokens } from "../../../context/token-estimator.js";
+import type { Conversation } from "../../../daemon/conversation.js";
+import type { RouteDefinition } from "../../http-router.js";
+import { conversationNotFoundResponse } from "./conversation-not-found.js";
+import { assertPlaygroundEnabled, type PlaygroundRouteDeps } from "./index.js";
+
+/**
+ * Build the `CompactionStateResponse` payload used by:
+ *  - GET ...playground/compaction-state (this file)
+ *  - POST ...playground/inject-compaction-failures (PR 7)
+ *  - POST ...playground/reset-compaction-circuit (PR 8)
+ *
+ * Exported so follow-up cleanup PRs can replace inline copies in PR 7 / PR 8
+ * with this canonical implementation.
+ */
+export function buildCompactionStateResponse(conversation: Conversation) {
+  const messages = conversation.getMessages();
+  const estimatedInputTokens = estimatePromptTokens(messages);
+  const cfg = getConfig().llm.default.contextWindow;
+  const maxInputTokens = cfg.maxInputTokens;
+  const compactThresholdRatio = cfg.compactThreshold;
+  const thresholdTokens = Math.floor(maxInputTokens * compactThresholdRatio);
+  const compactionCircuitOpenUntil = conversation.compactionCircuitOpenUntil;
+  return {
+    estimatedInputTokens,
+    maxInputTokens,
+    compactThresholdRatio,
+    thresholdTokens,
+    messageCount: messages.length,
+    contextCompactedMessageCount: conversation.contextCompactedMessageCount,
+    contextCompactedAt: conversation.contextCompactedAt,
+    consecutiveCompactionFailures: conversation.consecutiveCompactionFailures,
+    compactionCircuitOpenUntil,
+    isCircuitOpen:
+      compactionCircuitOpenUntil !== null &&
+      Date.now() < compactionCircuitOpenUntil,
+    isCompactionEnabled: cfg.enabled,
+  };
+}
+
+export function stateRouteDefinitions(
+  deps: PlaygroundRouteDeps,
+): RouteDefinition[] {
+  return [
+    {
+      endpoint: "conversations/:id/playground/compaction-state",
+      method: "GET",
+      policyKey: "conversations/playground/state",
+      summary: "Read current compaction state for a conversation",
+      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);
+        }
+
+        return Response.json(buildCompactionStateResponse(conversation));
+      },
+    },
+  ];
+}