@camox/api-contract 0.43.0 → 0.45.0

package/src/ids.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+/** The id of a content entity: one UUIDv7, kept in Live and every draft (ADR 0004). */
+export const uuidv7Schema = /* @__PURE__ */ z.uuidv7();
+
+/**
+ * A Project ID: a UUIDv7 in lowercase only, the form the project's Worker is named by, so an
+ * uppercase one fails here rather than silently naming no project.
+ */
+export const projectIdSchema = /* @__PURE__ */ z
+  .uuidv7()
+  .regex(/^[0-9a-f-]+$/, "A Project ID is a UUIDv7 in lowercase");
+
+/**
+ * `uuidv7Schema` as JSON Schema, for content schemas. Written out rather than derived, so site
+ * bundles, which need only this, leave zod out.
+ */
+export const uuidv7JsonSchema = {
+  type: "string",
+  format: "uuid",
+  pattern:
+    "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
+};
+
+/** A text link to a page: this prefix, then the page's UUIDv7. */
+export const PAGE_TEXT_LINK_PREFIX = "camox:page:";
+
+/**
+ * Mints a UUIDv7 (RFC 9562): a 48-bit millisecond timestamp, then random bits.
+ * The server mints ids; clients mint one only for optimistic inserts.
+ */
+export function generateUuidv7(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let timestamp = Date.now();
+  for (let index = 5; index >= 0; index--) {
+    bytes[index] = timestamp % 256;
+    timestamp = Math.floor(timestamp / 256);
+  }
+  bytes[6] = (bytes[6]! & 0x0f) | 0x70;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/index.ts

@@ -1 +1,7 @@
+export * from "./artifact.ts";
+export * from "./icons.ts";
+export * from "./ids.ts";
+export * from "./reference-query.ts";
 export type { Router } from "../../../apps/api/src/router";
+export type { PublishPreview } from "../../../apps/api/src/domains/drafts/publish";
+export type { EntityKind } from "../../../apps/api/src/domains/drafts/overlay";

package/src/projects.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+/**
+ * Project Slugs Camox keeps for its own hosts and pages, so no project's `<slug>.camox.site`
+ * looks like one of them.
+ */
+export const RESERVED_PROJECT_SLUGS: ReadonlySet<string> = new Set([
+  "www",
+  "api",
+  "app",
+  "dashboard",
+  "studio",
+  "sites",
+  "site",
+  "docs",
+  "blog",
+  "help",
+  "support",
+  "status",
+  "admin",
+  "auth",
+  "login",
+  "mail",
+  "email",
+  "cdn",
+  "static",
+  "assets",
+  "files",
+  "camox",
+]);
+
+/**
+ * A Project Slug: one lowercase DNS label, the only depth Universal SSL covers on `camox.site`,
+ * made of letters, digits and inner hyphens.
+ */
+export const projectSlugSchema = /* @__PURE__ */ z
+  .string()
+  .min(1, "Enter a slug")
+  .max(63, "Use at most 63 characters")
+  .regex(
+    /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+    "Use lowercase letters, digits and hyphens, without a hyphen at either end",
+  );
+
+/** Why a slug can't be given to a new project. */
+export type UnavailableSlugReason = "invalid" | "reserved" | "taken";
+
+/** What a member is told when a slug can't be used, by reason. */
+export const UNAVAILABLE_SLUG_MESSAGES: Record<UnavailableSlugReason, string> = {
+  invalid: "Use lowercase letters, digits and hyphens, without a hyphen at either end.",
+  reserved: "This slug is reserved by Camox. Choose another.",
+  taken: "This slug is already taken. Choose another.",
+};
+
+/**
+ * Where a project is in its life: `settingUp` from its creation until its first release
+ * succeeds, then `live`. `setupFailed` when its setup gave up: Camox is told and fixes it.
+ */
+export type ProjectStatus = "settingUp" | "live" | "setupFailed";
+
+/**
+ * The steps a project's setup goes through before it's live, as its page lists them: copying the
+ * Template into its repo, then its first release building it and serving it from its Worker.
+ */
+export type ProjectSetupStep = "copyTemplate" | "build" | "serve";
+
+export const PROJECT_SETUP_STEPS: readonly ProjectSetupStep[] = ["copyTemplate", "build", "serve"];

package/src/query-keys.ts

@@ -1,3 +1,5 @@
+import type { EndedDraft } from "./drafts";
+
 /**
  * Use TypeScript to enforce 'camox' as the first query key to ensure they're all namespaced.
  * This is because the Tanstack Query client on the frontend may be shared with the user's routes,
@@ -7,52 +9,88 @@ export type QueryKey = [first: "camox", ...rest: Array<string | number>];
 type QueryKeyGroup = Record<string, QueryKey | ((...args: any[]) => QueryKey)>;
 
 /**
- * Source axis on read query keys. `'live'` reads the page's live published
- * checkpoint snapshot; `'draft'` reads the live editor rows. The two render
- * through the same component — only the cache slot differs, so toggling the
- * source select is instant once both have been seeded.
- *
- * Block / page-read query keys include the source as the trailing key segment.
- * Omitting it on `invalidateQueries` is a prefix invalidation that hits every
- * source — used for navigation events and other source-agnostic invalidations.
- * Edit-time invalidations (which only touch draft data) pass `'draft'`
- * explicitly so the `'live'` cache stays untouched.
+ * The key prefixes the API's realtime invalidations name (ADR 0011). The studio caches each read
+ * under one of them, with the scope appended, so an invalidation reaches every read it should;
+ * the studio's own keys live with its reads, in the SDK.
  */
-export type ReadSource = "draft" | "live";
-
 export const queryKeys = {
+  collections: {
+    record: (projectUuid: string, collectionId: string, id: string) => [
+      "camox",
+      "collections",
+      "record",
+      projectUuid,
+      collectionId,
+      id,
+    ],
+    records: (projectUuid: string, collectionId: string) => [
+      "camox",
+      "collections",
+      "records",
+      projectUuid,
+      collectionId,
+    ],
+  },
   pages: {
     list: ["camox", "pages", "list"],
-    getByPath: (path: string, source?: ReadSource) =>
-      source
-        ? ["camox", "pages", "getByPath", path, source]
-        : ["camox", "pages", "getByPath", path],
+    getByPath: (path: string) => ["camox", "pages", "getByPath", path],
     getByPathAll: ["camox", "pages", "getByPath"],
-    getById: (id: number) => ["camox", "pages", "getById", id],
+    getById: (id: string) => ["camox", "pages", "getById", id],
   },
   files: {
     list: ["camox", "files", "list"],
-    get: (id: number) => ["camox", "files", "get", id],
+    get: (id: string) => ["camox", "files", "get", id],
   },
   blocks: {
-    get: (id: number, source?: ReadSource) =>
-      source ? ["camox", "blocks", "get", id, source] : ["camox", "blocks", "get", id],
+    get: (id: string) => ["camox", "blocks", "get", id],
+    // Every placement change refreshes what's under this prefix: counts, pages using a block.
     getUsageCounts: ["camox", "blocks", "getUsageCounts"],
-    getPageMarkdown: (pageId: number) => ["camox", "blocks", "getPageMarkdown", pageId],
-  },
-  repeatableItems: {
-    get: (id: number) => ["camox", "repeatableItems", "get", id],
+    // Under the usage counts prefix, so placing or removing the block refreshes it too.
+    getSyncedContent: (type: string) => ["camox", "blocks", "getUsageCounts", "synced", type],
+    getPageMarkdown: (pageId: string) => ["camox", "blocks", "getPageMarkdown", pageId],
   },
   layouts: {
     all: ["camox", "layouts"],
   },
-  environments: {
-    all: ["camox", "environments"],
-    checkCompatibility: ["camox", "environments", "checkCompatibility"],
+  drafts: {
+    all: ["camox", "drafts"],
+    // Open drafts and Live's latest publish: the same for every viewer, whatever they're in.
+    list: ["camox", "drafts", "list"],
+    // The draft a viewer is in, scoped to it like content.
+    get: ["camox", "drafts", "get"],
   },
 } satisfies Record<string, QueryKeyGroup>;
 
+/** The last segment of a query key: what the query reads, Live or a draft (ADR 0011). */
+export const LIVE_KEY_SCOPE = "live";
+
+/**
+ * A query key read from Live (`draftId` null) or from a draft. The keys above are prefixes naming
+ * what a query reads; the cache holds them with the scope appended, so each draft's queries are
+ * kept and invalidated apart.
+ */
+export function inScope(key: QueryKey, draftId: string | null): QueryKey {
+  return [...key, draftId ?? LIVE_KEY_SCOPE];
+}
+
+/** The scope a scoped query key ends in: `"live"` or a draft's id. */
+export function scopeOfKey(key: readonly unknown[]): unknown {
+  return key[key.length - 1];
+}
+
+/**
+ * Refetch the queries under these prefixes. `draftId` names the draft the change came from, so
+ * only that draft's queries refetch; a Live change (`null`) refetches every draft's too, since
+ * drafts read Live wherever they change nothing.
+ */
 export type InvalidationMessage = {
   type: "invalidate";
+  draftId: string | null;
   targets: QueryKey[];
 };
+
+/** A draft was published or discarded: its viewers go back to Live. */
+export type DraftEndedMessage = { type: "draftEnded" } & EndedDraft;
+
+/** Everything the project room broadcasts. */
+export type ProjectRoomMessage = InvalidationMessage | DraftEndedMessage;

package/src/reference-query.ts

@@ -0,0 +1,48 @@
+/**
+ * Rules for query-backed reference lists, shared by the SDK (builders) and the API (definition
+ * sync), so both accept and reject the same queries.
+ */
+
+/** The most records a query-backed list resolves to, and its default `limit`. */
+export const QUERY_LIMIT_CAP = 100;
+
+/** Record metadata a query can order by. Collections cannot name fields after them. */
+export type SystemOrderKey = "createdAt" | "publishedAt";
+export const SYSTEM_ORDER_KEYS: readonly SystemOrderKey[] = ["createdAt", "publishedAt"];
+
+export function isSystemOrderKey(key: string): key is SystemOrderKey {
+  return (SYSTEM_ORDER_KEYS as readonly string[]).includes(key);
+}
+
+/** Whether a reference list field is query-backed: code defines its records, nothing is stored. */
+export function isQueryBacked(field: object | null | undefined) {
+  return !!field && (field as { query?: unknown }).query !== undefined;
+}
+
+/**
+ * Why a query is invalid, if it is. `fieldTypeOf` gives the collection field type an ordering
+ * key names; keys must name a `String` field or system metadata.
+ */
+export function referenceQueryProblem(
+  query: unknown,
+  fieldTypeOf: (key: string) => unknown,
+): string | undefined {
+  if (!query || typeof query !== "object" || Array.isArray(query)) return "query must be an object";
+  const { orderBy, limit, ...rest } = query as Record<string, unknown>;
+  if (Object.keys(rest).length) return "query only supports orderBy and limit";
+  const validLimit =
+    typeof limit === "number" && Number.isInteger(limit) && limit >= 1 && limit <= QUERY_LIMIT_CAP;
+  if (limit !== undefined && !validLimit) {
+    return `limit must be an integer from 1 to ${QUERY_LIMIT_CAP}`;
+  }
+  if (orderBy === undefined) return;
+  const entries =
+    orderBy && typeof orderBy === "object" && !Array.isArray(orderBy)
+      ? Object.entries(orderBy)
+      : [];
+  if (entries.length !== 1) return "orderBy takes a single key";
+  const [[key, direction]] = entries;
+  if (direction !== "asc" && direction !== "desc") return 'order must be "asc" or "desc"';
+  if (isSystemOrderKey(key)) return;
+  if (fieldTypeOf(key) !== "String") return `cannot order by "${key}"`;
+}

package/src/threads.ts

@@ -0,0 +1,327 @@
+import type { AssistantMessage, Message } from "@earendil-works/pi-ai";
+import type { AgentEvent, EntryRecord } from "@earendil-works/pi-durable";
+import { z } from "zod";
+
+// A thread with Camox's agent, as the studio shows it. The thread's Durable Object sends Pi's own
+// agent events over its socket, and this module is the one place that interprets them: the
+// studio and the API's tests fold them with the same code.
+
+/**
+ * The kind of the transcript entry recording an editor's message, with its sender and the
+ * operation id the studio sent it with as data (`editorMessageDataSchema`).
+ */
+export const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
+
+/** The kind of the transcript entry recording that an editor stopped a run, with them as data. */
+export const RUN_STOPPED_ENTRY = "camox.run-stopped";
+
+/** Who sent a message in a thread. */
+export const threadSenderSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  image: z.string().nullable(),
+});
+export type ThreadSender = z.infer<typeof threadSenderSchema>;
+
+/** Whether `data` names a sender. */
+export const isSender = (data: unknown): data is ThreadSender =>
+  threadSenderSchema.safeParse(data).success;
+
+/** What an editor's message entry records: who sent it, and the operation id it was sent with. */
+export const editorMessageDataSchema = threadSenderSchema.extend({
+  operationId: z.string().optional(),
+});
+
+/**
+ * A draft a Live thread started with its first write, becoming its thread, and the operation ids
+ * of the messages of the run that made the write: the studio that sent one of them enters the
+ * draft with the thread.
+ */
+export const startedDraftSchema = z.object({
+  draftId: z.string(),
+  operationIds: z.array(z.string()),
+});
+export type StartedDraft = z.infer<typeof startedDraftSchema>;
+
+/** How a write touched what it names. */
+export const touchKindSchema = z.enum(["created", "edited", "moved", "deleted", "settings"]);
+export type TouchKind = z.infer<typeof touchKindSchema>;
+
+/**
+ * One thing a script's successful write touched, named so the studio can locate it: a Page (and
+ * its Block, if any), a Synced Block's shared content, by its block definition, or a Layout (and
+ * its Block, if any). `settings` is a Page's settings only (nickname, path, SEO, layout). `locale`
+ * is the Locale the write was in, for a localized tool. Writes to Collection Records, Files and
+ * Locales aren't on the Canvas, so they're left out.
+ */
+const touchBaseSchema = z.object({ kind: touchKindSchema, locale: z.string().optional() });
+
+export const touchSchema = z.discriminatedUnion("entity", [
+  touchBaseSchema.extend({
+    entity: z.literal("page"),
+    pageId: z.string(),
+    blockId: z.string().optional(),
+  }),
+  touchBaseSchema.extend({
+    entity: z.literal("synced-block"),
+    /** The Synced Block's block definition id. */
+    blockType: z.string(),
+  }),
+  touchBaseSchema.extend({
+    entity: z.literal("layout"),
+    layoutId: z.string(),
+    blockId: z.string().optional(),
+  }),
+]);
+export type Touch = z.infer<typeof touchSchema>;
+
+/**
+ * What one code-mode script's successful writes touched, in write order, and the operation ids
+ * of the messages of the run it belongs to: only the studio that sent one of them follows it.
+ */
+export const touchedBatchSchema = z.object({
+  operationIds: z.array(z.string()),
+  touches: z.array(touchSchema),
+});
+export type TouchedBatch = z.infer<typeof touchedBatchSchema>;
+
+/** A message the studio shows in a thread. */
+export type ThreadMessage =
+  | { id: string; from: "editor"; sender: ThreadSender; text: string }
+  /** The agent's final message of a turn, in Markdown. */
+  | { id: string; from: "agent"; text: string }
+  /**
+   * In place of the agent's message, for a turn that ended without one: the model failed (after
+   * Pi's retries), or its answer was cut short. Sending again retries.
+   */
+  | { id: string; from: "failed" }
+  /** In place of the agent's message, for a turn an editor stopped: `sender` stopped it. */
+  | { id: string; from: "stopped"; sender: ThreadSender };
+
+/** Where a Live thread's messages went when it started a draft, beside its transcript. */
+type LiveThreadHandoff = {
+  /**
+   * The draft this Live thread started with its first write, whose thread it became. The studio
+   * that sent a message of that run enters the draft with the thread; other tabs on Live move to
+   * the editor's fresh Live thread.
+   */
+  startedDraft?: StartedDraft;
+  /** The draft the editor's previous Live thread continued in, for a fresh Live thread. */
+  continuedIn?: StartedDraft;
+};
+
+/** Everything the studio shows for a thread. */
+export type ThreadView = LiveThreadHandoff & {
+  messages: readonly ThreadMessage[];
+  /** Whether a run is going: the agent is working on a turn, and stopping would end it. */
+  running: boolean;
+};
+
+export const EMPTY_THREAD_VIEW: ThreadView = { messages: [], running: false };
+
+/**
+ * What a thread's view is folded from: the steps of its transcript that matter to the studio,
+ * and whether a run is going. The studio and the tests fold Pi's events into this, and derive
+ * the view from it with `threadViewOf`, so a snapshot and the events that led to it show the same.
+ */
+export type ThreadState = LiveThreadHandoff & { steps: readonly ThreadStep[]; running: boolean };
+
+export const EMPTY_THREAD_STATE: ThreadState = { steps: [], running: false };
+
+/** One transcript entry, as far as the studio's view is concerned. */
+type ThreadStep = { id: string } & (
+  | { type: "editor"; sender: ThreadSender; text: string }
+  | { type: "answer"; text: string }
+  /** A round of tool calls, or their results: the run goes on after it. */
+  | { type: "tools" }
+  /** A model call that ended without an answer: failed, aborted, or cut short. */
+  | { type: "unfinished" }
+  | { type: "stopped"; sender: ThreadSender }
+);
+
+/** Studio → thread. */
+export const threadClientMessageSchema = z.discriminatedUnion("type", [
+  /**
+   * An editor's message. The operation id is generated by the studio and kept across resends, so
+   * a message resent after a dropped connection is one submission.
+   */
+  z.object({ type: z.literal("send"), operationId: z.string().min(1), text: z.string().min(1) }),
+  /** Stops the run going, if any. What the agent changed before stays. */
+  z.object({ type: z.literal("stop") }),
+  /** Asks for a fresh snapshot of the thread. */
+  z.object({ type: z.literal("resync") }),
+]);
+export type ThreadClientMessage = z.infer<typeof threadClientMessageSchema>;
+
+/** Thread → studio. */
+export type ThreadServerMessage =
+  /**
+   * Pi's agent events. The first batch after connecting or resyncing starts with a `snapshot`,
+   * which replaces whatever the studio folded before.
+   */
+  | { type: "events"; events: readonly AgentEvent[] }
+  /** The thread recorded the message sent with this operation id (once, however often sent). */
+  | { type: "accepted"; operationId: string }
+  /** This Live thread started a draft with its first write, and became that draft's thread. */
+  | { type: "started-draft"; startedDraft: StartedDraft }
+  /**
+   * The editor's previous Live thread continued in this draft: this one is fresh. Sent before
+   * the snapshot.
+   */
+  | { type: "continued-in"; continuedIn: StartedDraft }
+  /**
+   * A code-mode script that wrote something ended, failed or not: what its successful writes
+   * touched. Sent once per such script, live only: a snapshot never replays past touches.
+   */
+  | { type: "touched"; touched: TouchedBatch }
+  | { type: "error"; operationId?: string; message: string };
+
+/**
+ * The code a thread closes its sockets with once it ended with its draft, and for good: it's
+ * deleted, so reconnecting reaches nothing. A development draft, which stays open, gets a new
+ * thread the next time the studio connects.
+ */
+export const THREAD_ENDED_CLOSE_CODE = 4000;
+
+const textOf = (content: Message["content"]) =>
+  typeof content === "string"
+    ? content
+    : content
+        .flatMap((part) => (part.type === "text" ? [part.text] : []))
+        .join("")
+        .trim();
+
+/** What an assistant message is to the thread: a final answer, a tool round, or neither. */
+function assistantStep(id: string, message: AssistantMessage): ThreadStep {
+  if (message.content.some((part) => part.type === "toolCall")) return { id, type: "tools" };
+  // Thinking is never shown. An answer cut short by the model's length limit isn't one.
+  const text = message.stopReason === "stop" ? textOf(message.content) : "";
+  return text ? { id, type: "answer", text } : { id, type: "unfinished" };
+}
+
+/** The sender an entry's data names, if any, without other fields it may carry. */
+function senderOf(data: unknown): ThreadSender | undefined {
+  if (!isSender(data)) return undefined;
+  const { id, name, image } = data;
+  return { id, name, image };
+}
+
+/** The step an entry is, if it's one the view depends on. */
+function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
+  const id = String(entry.id);
+  const sender = senderOf(entry.data);
+  if (entry.kind === RUN_STOPPED_ENTRY && sender) return { id, type: "stopped", sender };
+  const message = entry.model?.find((candidate) => candidate.role !== "system");
+  if (!message) return undefined;
+  if (entry.kind === EDITOR_MESSAGE_ENTRY && message.role === "user" && sender) {
+    return { id, type: "editor", sender, text: textOf(message.content) };
+  }
+  if (message.role === "assistant") return assistantStep(id, message);
+  if (message.role === "toolResult") return { id, type: "tools" };
+  return undefined;
+}
+
+/**
+ * What the studio shows for a thread. A turn starts with an editor's message, and messages sent
+ * while it runs join it. It ends with the agent's final message; text written beside tool calls
+ * is never shown. A stopped turn shows who stopped it instead, and whatever its run wrote after
+ * the stop is left out. A turn that ended without either shows a failed line in its place: its
+ * run is over, or a later message started another run after its last model call came back
+ * unfinished. While Pi retries a failed call, the run goes on, so the turn shows as working.
+ */
+export function threadViewOf({ steps, running, ...drafts }: ThreadState): ThreadView {
+  const messages: ThreadMessage[] = [];
+  // The latest editor's message of a turn still waiting for the agent's message.
+  let waiting: string | undefined;
+  let unfinished = false;
+  /** Ends the turn waiting for the agent's message, if any. */
+  const endTurn = () => {
+    waiting = undefined;
+    unfinished = false;
+  };
+  /** Ends the turn waiting for the agent's message with a failed line, if any. */
+  const fail = () => {
+    if (waiting !== undefined) messages.push({ id: `${waiting}:failed`, from: "failed" });
+    endTurn();
+  };
+
+  for (const step of steps) {
+    switch (step.type) {
+      case "editor":
+        // Pi places a steering message only once a model call is settled: after a round of tool
+        // calls, or with the answer ending the run. Never between a failed call and its retry, so
+        // an editor's message after an unfinished call means that call's turn is over.
+        if (unfinished) fail();
+        messages.push({ id: step.id, from: "editor", sender: step.sender, text: step.text });
+        waiting = step.id;
+        break;
+      case "stopped":
+        if (waiting === undefined) break;
+        messages.push({ id: step.id, from: "stopped", sender: step.sender });
+        endTurn();
+        break;
+      case "answer":
+        // A stopped turn's run may still answer before it ends.
+        if (waiting === undefined && messages.at(-1)?.from === "stopped") break;
+        messages.push({ id: step.id, from: "agent", text: step.text });
+        endTurn();
+        break;
+      case "tools":
+        unfinished = false;
+        break;
+      case "unfinished":
+        unfinished = true;
+        break;
+    }
+  }
+  if (!running) fail();
+  return { ...drafts, messages, running };
+}
+
+const append = (state: ThreadState, entry: EntryRecord | undefined): ThreadState => {
+  const step = entry && threadStepOf(entry);
+  if (!step || state.steps.some((known) => known.id === step.id)) return state;
+  return { ...state, steps: [...state.steps, step] };
+};
+
+/** Folds one of Pi's agent events into the thread's state. */
+export function reduceThreadState(state: ThreadState, event: AgentEvent): ThreadState {
+  switch (event.type) {
+    case "snapshot":
+      return {
+        ...state,
+        steps: event.entries.flatMap((entry) => threadStepOf(entry) ?? []),
+        running: event.run !== undefined,
+      };
+    case "run_start":
+      return { ...state, running: true };
+    case "run_end":
+      return { ...state, running: false };
+    case "message_end":
+    case "entry_appended":
+    case "tool_execution_end":
+      return append(state, event.entry);
+    default:
+      return state;
+  }
+}
+
+/** Folds a batch of Pi's agent events into the thread's state. */
+export const reduceThreadEvents = (
+  state: ThreadState,
+  events: readonly AgentEvent[],
+): ThreadState => events.reduce(reduceThreadState, state);
+
+/** Folds what the thread sent over its socket into the thread's state. */
+export function reduceThreadFrame(state: ThreadState, frame: ThreadServerMessage): ThreadState {
+  switch (frame.type) {
+    case "events":
+      return reduceThreadEvents(state, frame.events);
+    case "started-draft":
+      return { ...state, startedDraft: frame.startedDraft };
+    case "continued-in":
+      return { ...state, continuedIn: frame.continuedIn };
+    default:
+      return state;
+  }
+}