@data-club/ai-hub-server 0.0.1

package/src/routes/sessions.ts

@@ -0,0 +1,1878 @@
+/**
+ * User-facing `/sessions/*` — the caller's own sessions (never cross-user).
+ *
+ * Step 4 ships the four CRUD endpoints minus DELETE (sessions are archive-only
+ * in v1 — §6.3.1). The Letta-conversation-create call on `POST /sessions` is
+ * stubbed; Step 5 replaces the placeholder with `client.conversations.create`.
+ *
+ * - `POST /sessions` — body `{ agent_id, title }`; title required (1..80
+ *   chars). Creates a session owned by the caller against `agent_id`. The
+ *   server snapshots `agent.letta_agent_id` into `session.letta_agent_id` and
+ *   stores a placeholder `letta_conversation_id` (Step 5 fills the real one).
+ *   Rejects when the agent is archived (`agent_archived`).
+ * - `GET /sessions?agent_id=...&include_archived=false` — caller-scoped list.
+ *   `agent_id` is required; `include_archived` defaults to false.
+ * - `GET /sessions/:id` — single session if the caller owns it; 404 with no
+ *   enumeration leakage otherwise.
+ * - `PATCH /sessions/:id` — body `{ title?, is_archived? }`. Rename and / or
+ *   archive / unarchive. An empty patch is a 200 no-op.
+ * - `GET /sessions/:id/messages` — 501 stub; Step 5 wires
+ *   `client.conversations.messages.list`.
+ *
+ * @see SPECIFICATIONS.md §6.3.1 — Sessions
+ * @see SPECIFICATIONS.md §11 — `session` table
+ * @see SPECIFICATIONS.md §13.2 — user isolation
+ */
+
+import { randomUUID } from "node:crypto";
+
+import { and, desc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import type { AIHubMessage, AIHubToolCallRecord } from "@data-club/ai-hub";
+
+import { protectedRoute } from "../auth/middleware.js";
+import {
+  agent,
+  messageOverride,
+  messageUsage,
+  rotatingMessage,
+  session,
+  turn,
+} from "../db/schema.js";
+import type { SessionRow } from "../db/schema.js";
+import type { DrizzleDB } from "../db/connection.js";
+import {
+  conflictError,
+  internalError,
+  jsonResponse,
+  notFound,
+  validationError,
+} from "../handlers/responses.js";
+import type { RouteHandler } from "../handlers/types.js";
+import { ForkSourceNotFoundError } from "../letta/client.js";
+import {
+  materializeSandbox,
+  purgeSandbox,
+  resolveSandboxDir,
+  resolveSeedDir,
+} from "../letta/sandbox.js";
+
+// Per-model reasoning capability detection lives in Letta Code itself;
+// ai-hub no longer publishes a `capabilities` map on session responses.
+// The `reasoning.{effort,verbosity,thinking_budget}` columns on `session`
+// are kept for forward compatibility with `PATCH /sessions/:id/reasoning`
+// but are not forwarded to Letta Code in v1.x.
+type ReasoningCapabilities = Record<string, never>;
+import type { LettaMessage } from "../letta/types.js";
+
+// Letta's prompt compiler appends a trailing `<memory_metadata>…</memory_metadata>`
+// block to every persisted `system_message.content` with agent id /
+// conversation id / recall-message count. Useful for the LLM but noise
+// for the chat-UI display, so we strip it before returning to the client.
+const MEMORY_METADATA_REGEX = /\s*<memory_metadata>[\s\S]*?<\/memory_metadata>\s*$/;
+function stripMemoryMetadata(content: string): string {
+  return content.replace(MEMORY_METADATA_REGEX, "");
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Wire shape                                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Wire-format session row returned to the client. The Letta-side ids
+ * (`letta_conversation_id`, `letta_agent_id`) are server-internal and
+ * deliberately omitted — the React client only ever sees ai-hub ids.
+ *
+ * @param row - the `session` row.
+ * @returns the JSON-safe response shape.
+ */
+function sessionView(
+  row: SessionRow,
+  extras?: {
+    /** Per-model reasoning capability map. Included only when the caller
+     *  wants the per-session selector to render (i.e. on `GET /sessions/:id`).
+     *  Omitted on list responses to save a Letta call per row. */
+    capabilities?: ReasoningCapabilities;
+  },
+): Record<string, unknown> {
+  return {
+    id: row.id,
+    user_id: row.userId,
+    agent_id: row.agentId,
+    title: row.title,
+    is_archived: row.isArchived,
+    reasoning: {
+      effort: row.reasoningEffort,
+      verbosity: row.verbosity,
+      thinking_budget: row.thinkingBudget,
+    },
+    ...(extras?.capabilities !== undefined && { capabilities: extras.capabilities }),
+    created_at: row.createdAt,
+    updated_at: row.updatedAt,
+  };
+}
+
+/** Current ISO-8601 timestamp with millisecond precision. */
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Resolution of an agent's `fork_source_conversation_id` to a concrete Letta
+ * conversation to fork at session-create.
+ *
+ * - `none`           — no base configured; start a brand-new conversation.
+ * - `ready`          — fork `conversationId` (a raw `conv-…`, or a rotating
+ *                      message's current prepared conversation).
+ * - `rmsg_missing`   — the `rmsg-…` reference points at a deleted/archived
+ *                      rotating message (operator misconfiguration).
+ * - `rmsg_not_ready` — the rotating message exists but hasn't produced a
+ *                      conversation yet (no successful rotation so far).
+ */
+type ForkSourceResolution =
+  | { kind: "none" }
+  | { kind: "ready"; conversationId: string }
+  | { kind: "rmsg_missing"; ref: string }
+  | { kind: "rmsg_not_ready"; ref: string };
+
+/**
+ * Resolves an agent's configured fork source. A plain `conv-…` id passes
+ * through unchanged (today's static base-conversation behavior); an `rmsg-…`
+ * reference is dereferenced to the rotating message's current prepared
+ * conversation. Pure DB read — no Letta call.
+ *
+ * @param db - Drizzle handle.
+ * @param forkSourceConversationId - the agent's stored value (may be null).
+ * @returns the resolution variant.
+ */
+function resolveForkSource(
+  db: DrizzleDB,
+  forkSourceConversationId: string | null,
+): ForkSourceResolution {
+  if (!forkSourceConversationId) return { kind: "none" };
+  if (!forkSourceConversationId.startsWith("rmsg-")) {
+    return { kind: "ready", conversationId: forkSourceConversationId };
+  }
+  const rmsg = db
+    .select()
+    .from(rotatingMessage)
+    .where(eq(rotatingMessage.id, forkSourceConversationId))
+    .get();
+  if (!rmsg || rmsg.isArchived) {
+    return { kind: "rmsg_missing", ref: forkSourceConversationId };
+  }
+  if (!rmsg.currentConversationId) {
+    return { kind: "rmsg_not_ready", ref: forkSourceConversationId };
+  }
+  return { kind: "ready", conversationId: rmsg.currentConversationId };
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /sessions                                                            */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** `POST /sessions` body. `title` is non-empty, 1..80 chars. */
+const createSessionSchema = z
+  .object({
+    agent_id: z.string().uuid(),
+    title: z.string().min(1).max(80),
+  })
+  .strict();
+
+/**
+ * `POST /sessions` — create a new session for the caller against `agent_id`.
+ *
+ * Validates that the referenced ai-hub agent exists and is not archived.
+ * Snapshots `agent.letta_agent_id` so a future re-point of the catalog entry
+ * does not migrate existing conversations.
+ *
+ * Step 5 replaces the placeholder `letta_conversation_id` with a real SDK
+ * call to `client.conversations.create`.
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export const handleCreateSession: RouteHandler = protectedRoute(
+  {},
+  async (req, ctx, auth) => {
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = createSessionSchema.safeParse(raw);
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      let code: string = "validation";
+      if (issue?.path[0] === "title") {
+        if (issue.code === "too_small") code = "title_required";
+        else if (issue.code === "too_big") code = "title_too_long";
+      }
+      return validationError(issue?.message ?? "Invalid request body.", code);
+    }
+
+    const agentRow = ctx.db
+      .select()
+      .from(agent)
+      .where(eq(agent.id, parsed.data.agent_id))
+      .get();
+    if (!agentRow) return notFound("Agent not found.");
+    if (agentRow.isArchived) {
+      return conflictError(
+        "agent_archived",
+        "Cannot start a new session against an archived agent.",
+      );
+    }
+
+    // Branch on `agent.fork_source_conversation_id`:
+    //   set  → fork an operator-curated base conversation in Letta. The value
+    //          is either a raw `conv-…` (static base, Step 12.5) or an
+    //          `rmsg-…` reference to a rotating starting message, resolved to
+    //          its current prepared conversation here.
+    //   null → create a brand-new conversation (today's behavior).
+    //
+    // Both paths surface SDK failures as 500 — admin-side validation is
+    // responsible for catching the configuration-shape problems (missing
+    // source, wrong agent) before any user-facing session-create reaches
+    // here. A 404 from fork at this point means the operator deleted the
+    // source between admin-validate and now.
+    const forkResolution = resolveForkSource(ctx.db, agentRow.forkSourceConversationId);
+    if (forkResolution.kind === "rmsg_missing") {
+      ctx.logger.error(
+        {
+          event: "session_rotating_message_missing",
+          agent_id: agentRow.id,
+          fork_source_conversation_id: agentRow.forkSourceConversationId,
+        },
+        "Agent references a rotating starting message that no longer exists or is archived.",
+      );
+      return internalError("Configured rotating starting message is unavailable.");
+    }
+    if (forkResolution.kind === "rmsg_not_ready") {
+      ctx.logger.error(
+        {
+          event: "session_rotating_message_not_ready",
+          agent_id: agentRow.id,
+          fork_source_conversation_id: agentRow.forkSourceConversationId,
+        },
+        "Rotating starting message has not produced a prepared conversation yet.",
+      );
+      return internalError(
+        "The rotating starting message has not generated its first conversation yet. Try again shortly.",
+      );
+    }
+    const forkSourceId =
+      forkResolution.kind === "ready" ? forkResolution.conversationId : null;
+
+    let conv: { id: string };
+    try {
+      if (forkSourceId) {
+        conv = await ctx.lettaClient.forkConversation(forkSourceId);
+      } else {
+        conv = await ctx.lettaClient.createConversation(agentRow.lettaAgentId);
+      }
+    } catch (err) {
+      if (err instanceof ForkSourceNotFoundError) {
+        ctx.logger.error(
+          {
+            event: "letta_fork_source_not_found",
+            agent_id: agentRow.id,
+            fork_source_conversation_id: agentRow.forkSourceConversationId,
+          },
+          "Letta fork-source conversation no longer exists.",
+        );
+        return internalError(
+          "Configured base conversation no longer exists in Letta.",
+        );
+      }
+      ctx.logger.error(
+        {
+          event: "letta_create_conversation_failed",
+          agent_id: agentRow.id,
+          letta_agent_id: agentRow.lettaAgentId,
+          fork: !!agentRow.forkSourceConversationId,
+          err: err instanceof Error ? err.message : String(err),
+        },
+        "Letta conversation creation failed.",
+      );
+      return internalError("Failed to create Letta conversation.");
+    }
+
+    const id = randomUUID();
+    ctx.db
+      .insert(session)
+      .values({
+        id,
+        userId: auth.user.id,
+        agentId: agentRow.id,
+        lettaConversationId: conv.id,
+        lettaAgentId: agentRow.lettaAgentId,
+        title: parsed.data.title,
+        isArchived: false,
+      })
+      .run();
+
+    // Step-12.5 — if the agent has a sandbox seed configured, recursively
+    // copy the seed folder into `{filesDir}/sandboxes/{session_id}/` and
+    // record the absolute path on the session row. On copy failure, roll
+    // back: best-effort delete the partial sandbox dir + the just-created
+    // Letta conversation, then 500. Better to surface the error to the
+    // caller than to leave a dangling conversation + half-written folder.
+    if (agentRow.sandboxSeedName) {
+      const targetDir = resolveSandboxDir(ctx.filesDir, id);
+      let seedDir: string;
+      try {
+        seedDir = resolveSeedDir(ctx.filesDir, agentRow.sandboxSeedName);
+      } catch (err) {
+        // Programmer error — should have been caught at admin-write time.
+        ctx.logger.error(
+          {
+            event: "session_sandbox_invalid_seed_name",
+            agent_id: agentRow.id,
+            sandbox_seed_name: agentRow.sandboxSeedName,
+            err: err instanceof Error ? err.message : String(err),
+          },
+          "Invalid sandbox_seed_name reached POST /sessions; should have been caught at admin-write.",
+        );
+        ctx.db.delete(session).where(eq(session.id, id)).run();
+        return internalError("Failed to materialize session sandbox.");
+      }
+      try {
+        await materializeSandbox(seedDir, targetDir);
+      } catch (err) {
+        ctx.logger.error(
+          {
+            event: "session_sandbox_materialize_failed",
+            session_id: id,
+            agent_id: agentRow.id,
+            sandbox_seed_name: agentRow.sandboxSeedName,
+            err: err instanceof Error ? err.message : String(err),
+          },
+          "Failed to materialize per-session sandbox folder.",
+        );
+        // Best-effort rollback: drop the just-inserted session row +
+        // the partially-copied folder. The Letta conversation is left
+        // in place — Letta doesn't expose a server-side delete that
+        // ai-hub uses (§6.4.1's deprecated-surfaces table), and the
+        // orphan conversation is harmless (no users / sessions reach
+        // it from ai-hub).
+        ctx.db.delete(session).where(eq(session.id, id)).run();
+        await purgeSandbox(targetDir).catch(() => {
+          /* best effort */
+        });
+        return internalError("Failed to materialize session sandbox.");
+      }
+      ctx.db
+        .update(session)
+        .set({ sandboxDir: targetDir, updatedAt: new Date().toISOString() })
+        .where(eq(session.id, id))
+        .run();
+    }
+
+    const row = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!row) throw new Error("Just-inserted session vanished.");
+
+    ctx.logger.info(
+      {
+        user_id: auth.user.id,
+        session_id: row.id,
+        agent_id: agentRow.id,
+        forked: !!agentRow.forkSourceConversationId,
+        sandboxed: !!agentRow.sandboxSeedName,
+        event: "session_created",
+      },
+      "Session created.",
+    );
+    return jsonResponse(201, sessionView(row));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /sessions?agent_id=...&include_archived=...                            */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /sessions` — list the caller's sessions for a given agent.
+ *
+ * Query parameters:
+ *
+ * - `agent_id` — required. The ai-hub agent (catalog entry) to scope the list
+ *   to. Sessions for other agents are not returned (a single GET is
+ *   per-agent, mirroring how the React sessions panel mounts inside an
+ *   opened agent — see [03-chat.md](../../../../docs/ui-sketches/03-chat.md)).
+ * - `include_archived` — optional, default `false`. When `true`, archived
+ *   rows are surfaced alongside active ones with their `is_archived` flag
+ *   set; the client distinguishes them visually (`--archived` modifier).
+ *
+ * Order: newest first by `updated_at`.
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export const handleListSessions: RouteHandler = protectedRoute(
+  {},
+  async (req, _ctx, auth) => {
+    const url = new URL(req.url);
+    const agentId = url.searchParams.get("agent_id");
+    if (!agentId) {
+      return validationError(
+        "Query parameter `agent_id` is required.",
+        "agent_id_required",
+      );
+    }
+    const includeArchived =
+      url.searchParams.get("include_archived")?.toLowerCase() === "true";
+
+    const ctx = _ctx; // alias for clarity
+    const where = includeArchived
+      ? and(eq(session.userId, auth.user.id), eq(session.agentId, agentId))
+      : and(
+          eq(session.userId, auth.user.id),
+          eq(session.agentId, agentId),
+          eq(session.isArchived, false),
+        );
+    const rows = ctx.db
+      .select()
+      .from(session)
+      .where(where)
+      .orderBy(desc(session.updatedAt))
+      .all();
+    return jsonResponse(200, {
+      sessions: rows.map((r) => sessionView(r)),
+    });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /sessions/:id                                                         */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /sessions/:id` — single session, owner-scoped.
+ *
+ * Returns 404 with `not_found` for both "no such session" and "exists but
+ * belongs to another user" — no enumeration leakage (§13.1).
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export const handleGetSession: RouteHandler = protectedRoute(
+  {},
+  async (_req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    const row = ctx.db
+      .select()
+      .from(session)
+      .where(eq(session.id, id))
+      .get();
+    if (!row || row.userId !== auth.user.id) return notFound();
+
+    // Per-model reasoning capabilities are no longer published — see
+    // migration note at top of file. Empty object preserves the shape
+    // for React clients that read the field defensively.
+    return jsonResponse(200, sessionView(row, { capabilities: {} }));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  PATCH /sessions/:id                                                       */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Body for `PATCH /sessions/:id`. At least one field must be present; an empty patch is also fine (no-op). */
+const patchSessionSchema = z
+  .object({
+    title: z.string().min(1).max(80).optional(),
+    is_archived: z.boolean().optional(),
+  })
+  .strict();
+
+/**
+ * `PATCH /sessions/:id` — rename and / or archive / unarchive, owner-scoped.
+ *
+ * Accepts either field independently — the React UI sends just `title` for
+ * rename and just `is_archived` for archive/unarchive. An empty body
+ * (`{}`) is a 200 no-op that echoes the row unchanged.
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export const handlePatchSession: RouteHandler = protectedRoute(
+  {},
+  async (req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = patchSessionSchema.safeParse(raw);
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      let code: string = "validation";
+      if (issue?.path[0] === "title") {
+        if (issue.code === "too_small") code = "title_required";
+        else if (issue.code === "too_big") code = "title_too_long";
+      }
+      return validationError(issue?.message ?? "Invalid request body.", code);
+    }
+    const body = parsed.data;
+
+    const row = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!row || row.userId !== auth.user.id) return notFound();
+
+    if (body.title !== undefined || body.is_archived !== undefined) {
+      const update: Partial<typeof session.$inferInsert> = {
+        updatedAt: nowIso(),
+      };
+      if (body.title !== undefined) update.title = body.title;
+      if (body.is_archived !== undefined) update.isArchived = body.is_archived;
+      ctx.db.update(session).set(update).where(eq(session.id, id)).run();
+      ctx.logger.info(
+        {
+          user_id: auth.user.id,
+          session_id: id,
+          patch: {
+            title: body.title !== undefined,
+            is_archived: body.is_archived,
+          },
+          event: "session_patched",
+        },
+        "Session updated.",
+      );
+    }
+
+    const fresh = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!fresh) return notFound();
+    return jsonResponse(200, sessionView(fresh));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  PATCH /sessions/:id/reasoning                                             */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Body for `PATCH /sessions/:id/reasoning`. Fields are independent — the
+ * React UI may send just `effort`, just `verbosity`, or both depending on
+ * what the agent's model supports.
+ *
+ * Values are stored as-typed: server-side validation against the per-model
+ * capability enum is intentionally LOOSE so this layer stays schema-driven.
+ * The actual rejection (if any) happens when Letta receives the patched
+ * `model_settings` before the turn — matching Letta Code's behavior.
+ *
+ * `null` explicitly clears a field; omitting it keeps the existing value.
+ */
+const patchSessionReasoningSchema = z
+  .object({
+    effort: z.string().nullable().optional(),
+    verbosity: z.string().nullable().optional(),
+    thinking_budget: z.number().int().positive().nullable().optional(),
+  })
+  .strict();
+
+/**
+ * `PATCH /sessions/:id/reasoning` — update the user's per-session reasoning
+ * settings. Applied to the agent's `model_settings` automatically before
+ * the next chat turn.
+ *
+ * Owner-scoped: returns 404 for sessions the caller doesn't own.
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export const handlePatchSessionReasoning: RouteHandler = protectedRoute(
+  {},
+  async (req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = patchSessionReasoningSchema.safeParse(raw);
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      return validationError(issue?.message ?? "Invalid request body.");
+    }
+    const body = parsed.data;
+
+    const row = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!row || row.userId !== auth.user.id) return notFound();
+
+    const update: Partial<typeof session.$inferInsert> = { updatedAt: nowIso() };
+    if (body.effort !== undefined) update.reasoningEffort = body.effort;
+    if (body.verbosity !== undefined) update.verbosity = body.verbosity;
+    if (body.thinking_budget !== undefined) update.thinkingBudget = body.thinking_budget;
+    ctx.db.update(session).set(update).where(eq(session.id, id)).run();
+
+    ctx.logger.info(
+      {
+        user_id: auth.user.id,
+        session_id: id,
+        reasoning: {
+          effort: body.effort,
+          verbosity: body.verbosity,
+          thinking_budget: body.thinking_budget,
+        },
+        event: "session_reasoning_patched",
+      },
+      "Session reasoning updated.",
+    );
+
+    const fresh = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!fresh) return notFound();
+    return jsonResponse(200, sessionView(fresh, { capabilities: {} }));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /sessions/:id/messages — Step 5 placeholder                            */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /sessions/:id/messages` — paginated history pulled from Letta.
+ *
+ * Calls `client.conversations.messages.list(conversation_id)` per §6.4 and
+ * projects the result into the wire-shaped `AIHubMessage` array the
+ * React client consumes. Letta is the source of truth for message
+ * history (§6.8); ai-hub does not duplicate it in its SQLite.
+ *
+ * Owner-scoped: returns 404 for sessions not owned by the caller. The
+ * `power_user`+ "all-sessions overview" lives at `/admin/sessions`, not
+ * here.
+ *
+ * @see SPECIFICATIONS.md §6.3.1 — sessions
+ * @see SPECIFICATIONS.md §6.4 — SDK-only rule
+ * @see SPECIFICATIONS.md §6.8 — Letta owns message history
+ */
+export const handleGetSessionMessages: RouteHandler = protectedRoute(
+  {},
+  async (_req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    const row = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!row || row.userId !== auth.user.id) return notFound();
+    return buildSessionMessagesResponse(ctx, row);
+  },
+);
+
+/**
+ * `GET /admin/sessions/:id/messages` — read-only session detail for the
+ * admin sessions overview (§8.2, [07-admin-sessions-overview.md]).
+ *
+ * Mirrors `handleGetSessionMessages` but skips the owner check — power_user+
+ * can view any session in the deployment (no write surface; the React side
+ * mounts the same `<MessageBubble />`s without input controls).
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin sessions overview
+ * @see ui-sketches/07-admin-sessions-overview.md
+ */
+export const handleAdminGetSessionMessages: RouteHandler = protectedRoute(
+  { requiredRole: "power_user" },
+  async (_req, ctx, _auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    const row = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!row) return notFound();
+    return buildSessionMessagesResponse(ctx, row);
+  },
+);
+
+/**
+ * Fetches Letta history for the given session, projects it into the
+ * wire-shaped `AIHubMessage[]`, applies the message-override layer +
+ * `<memory_metadata>` stripping + per-assistant usage attachment, and
+ * returns the final JSON response.
+ *
+ * Shared between the owner-scoped `/sessions/:id/messages` and the
+ * power_user+ `/admin/sessions/:id/messages` — the only difference is the
+ * access check the caller performs **before** invoking this helper.
+ *
+ * @param ctx - server context (carries db + lettaClient + logger).
+ * @param row - the resolved session row (the caller's own row for the
+ *   user-facing route; any session for the admin route).
+ * @returns the projected response, or an `internalError` Response on Letta
+ *   list failure.
+ */
+async function buildSessionMessagesResponse(
+  ctx: import("../handlers/types.js").AIHubServerContext,
+  row: SessionRow,
+): Promise<Response> {
+  const id = row.id;
+  let messages: ReadonlyArray<LettaMessage>;
+  try {
+    messages = await ctx.lettaClient.listMessages(row.lettaConversationId);
+  } catch (err) {
+    ctx.logger.error(
+      {
+        event: "letta_list_messages_failed",
+        session_id: id,
+        letta_conversation_id: row.lettaConversationId,
+        err: err instanceof Error ? err.message : String(err),
+      },
+      "Letta message listing failed.",
+    );
+    return internalError("Failed to load message history.");
+  }
+  return projectAndRespond(ctx, row, messages);
+}
+
+/**
+ * Pure-ish projector — given the Letta listMessages result for a session,
+ * builds the final `{ messages }` JSON response.
+ *
+ * Split out from {@link buildSessionMessagesResponse} so the Letta-side
+ * fetch can be mocked / faked at the boundary in tests without re-implementing
+ * the projection. (DB reads for the overrides / usage tables stay inline —
+ * they're synchronous Drizzle calls keyed by ids already in scope.)
+ *
+ * @param ctx - server context.
+ * @param row - the session row.
+ * @param messages - raw Letta message list.
+ * @returns the projected response.
+ */
+function projectAndRespond(
+  ctx: import("../handlers/types.js").AIHubServerContext,
+  row: SessionRow,
+  messages: ReadonlyArray<LettaMessage>,
+): Response {
+
+    // Letta groups one logical assistant turn into multiple message-type
+    // rows. In single-step runs they share the same `id`; in
+    // **multi-step** runs (reasoning → tool call → tool return → final
+    // assistant text) each step gets its own `id`, so grouping by id
+    // alone misses the cross-step affordances.
+    //
+    // We aggregate by **turn** instead: walk the rows in chronological
+    // order, accumulating reasoning text + tool-call records into a
+    // current-turn buffer; when an `assistant_message` row arrives we
+    // attach the buffer to that row's id and reset. A `user_message`
+    // row also resets the buffer (defensive — guards against runs
+    // where the agent emits intermediate "thinking" output without a
+    // terminating assistant_message).
+    //
+    // Step-10 surfaces reasoning + tool-call data inside the assistant
+    // bubble (see SPECIFICATIONS.md §7.3, §10.4), so this aggregation
+    // is what makes the historical view match the live-streaming
+    // bubble.
+    const sortedRaw = [...messages].sort((a, b) => {
+      const aT = Date.parse((a as { date?: string }).date ?? "");
+      const bT = Date.parse((b as { date?: string }).date ?? "");
+      if (Number.isNaN(aT) && Number.isNaN(bT)) return 0;
+      if (Number.isNaN(aT)) return 1;
+      if (Number.isNaN(bT)) return -1;
+      return aT - bT;
+    });
+    const { byAssistantId: aggregates, orphanRuns } = collectAggregates(
+      sortedRaw as LettaMessage[],
+    );
+    const priority: Record<AIHubMessage["role"], number> = {
+      assistant: 3,
+      user: 2,
+      system: 1,
+      tool: 0,
+    };
+    const dedupedById = new Map<string, AIHubMessage>();
+    for (const raw of sortedRaw) {
+      const projected = toWireMessage(raw);
+      if (!projected) continue;
+      // Attach aggregates to assistant_messages; user/system are left
+      // untouched (they don't carry reasoning or tool calls).
+      let withAggregates: AIHubMessage = projected;
+      if (projected.role === "assistant") {
+        const agg = aggregates.get(projected.id);
+        if (agg) {
+          const next: AIHubMessage = { ...projected };
+          if (agg.reasoning.length > 0) {
+            next.reasoning = agg.reasoning;
+          }
+          if (agg.toolCalls.length > 0) {
+            next.tool_calls = agg.toolCalls;
+          }
+          withAggregates = next;
+        }
+      }
+      const incumbent = dedupedById.get(projected.id);
+      if (
+        !incumbent ||
+        priority[withAggregates.role] > priority[incumbent.role]
+      ) {
+        dedupedById.set(projected.id, withAggregates);
+      }
+    }
+
+    // Synthesize virtual assistant bubbles for orphan runs (runs that
+    // produced reasoning / tool calls but never emitted an
+    // assistant_message). Each gets a synthetic id derived from the
+    // run_id; created_at is the latest date observed in the run, which
+    // places the bubble correctly in the chronological sort below.
+    for (const orphan of orphanRuns) {
+      const synthId = `synth-run-${orphan.runId}`;
+      // Don't clobber a real message that happened to use the same id
+      // (impossible in practice — Letta doesn't issue ids in this
+      // shape — but cheap to guard).
+      if (dedupedById.has(synthId)) continue;
+      const virtualBubble: AIHubMessage = {
+        id: synthId,
+        role: "assistant",
+        content: "",
+        created_at: orphan.latestDate,
+        ...(orphan.aggregate.reasoning.length > 0
+          ? { reasoning: orphan.aggregate.reasoning }
+          : {}),
+        ...(orphan.aggregate.toolCalls.length > 0
+          ? { tool_calls: orphan.aggregate.toolCalls }
+          : {}),
+      };
+      dedupedById.set(synthId, virtualBubble);
+    }
+
+    // Letta's `messages.list` returns rows in the SDK's iteration order,
+    // which is not guaranteed to be chronological (in practice often
+    // reverse-chronological). The React chat renders bubbles top-to-bottom
+    // in the order received, so sort ascending by `date` here — the
+    // ordering is part of the §6.3.1 contract, not a UI concern. Stable
+    // sort: messages with identical timestamps keep Letta's relative order.
+    const sorted = [...dedupedById.values()].sort((a, b) => {
+      const aT = Date.parse(a.created_at);
+      const bT = Date.parse(b.created_at);
+      if (Number.isNaN(aT) || Number.isNaN(bT)) return 0;
+      return aT - bT;
+    });
+
+    // Apply content overrides.
+    //
+    // **DB-backed overrides** (`message_override` table) win over the raw
+    // wire content. Keyed by `(conversation_id, ordinal_position)` where
+    // position is the 0-based index into Letta's chronologically-sorted
+    // raw message list (`sortedRaw`). We compute that position for each
+    // Letta-issued id once and look it up per surviving wire message.
+    // Synthetic `synth-run-*` bubbles have no raw counterpart and are
+    // skipped. If no override applies, the wire message passes through
+    // untouched apart from `<memory_metadata>` stripping on system rows.
+    const positionByLettaId = new Map<string, number>();
+    sortedRaw.forEach((raw, idx) => {
+      const id = (raw as { id?: string }).id;
+      if (typeof id === "string") positionByLettaId.set(id, idx);
+    });
+    const overrideRows = ctx.db
+      .select()
+      .from(messageOverride)
+      .where(eq(messageOverride.conversationId, row.lettaConversationId))
+      .all();
+    // Only the `user_override` layer is consulted at display time.
+    // `system_override` is stored but inert (see `db/schema.ts` for
+    // rationale). Rows where `user_override` is null contribute nothing
+    // to display and are skipped.
+    const overrideByPosition = new Map<number, string>();
+    for (const o of overrideRows) {
+      if (o.userOverride !== null) {
+        overrideByPosition.set(o.ordinalPosition, o.userOverride);
+      }
+    }
+
+    // Per-assistant-message usage (cache hits/writes + token counts).
+    // Stamped by the runner on the last assistant message of each
+    // turn (see turnRunner.ts step 5.5). Renders as the cache badge
+    // on the chat UI's assistant bubbles.
+    const usageRows = ctx.db
+      .select()
+      .from(messageUsage)
+      .where(eq(messageUsage.sessionId, row.id))
+      .all();
+    const usageByMessageId = new Map<string, AIHubMessage["usage"]>();
+    for (const u of usageRows) {
+      usageByMessageId.set(u.lettaMessageId, {
+        input: u.promptTokens,
+        output: u.completionTokens,
+        cache_read: u.cachedInputTokens,
+        cache_write: u.cacheWriteTokens,
+        reasoning: u.reasoningTokens,
+        context: u.contextTokens,
+        total: u.totalTokens,
+      });
+    }
+
+    const projected = sorted.map((msg): AIHubMessage => {
+      const pos = positionByLettaId.get(msg.id);
+      const usage = usageByMessageId.get(msg.id);
+      const withUsage = usage !== undefined ? { ...msg, usage } : msg;
+      if (pos !== undefined) {
+        const explicit = overrideByPosition.get(pos);
+        if (explicit !== undefined) {
+          return { ...withUsage, content: explicit };
+        }
+      }
+      if (msg.role === "system") {
+        const stripped = stripMemoryMetadata(msg.content);
+        if (stripped !== msg.content) {
+          return { ...withUsage, content: stripped };
+        }
+      }
+      return withUsage;
+    });
+
+    return jsonResponse(200, { messages: projected });
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /sessions/:id/message-overrides                                       */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Wire shape for one row in the message-override list. */
+interface MessageOverrideView {
+  /** 0-based index into Letta's chronologically-sorted message list. */
+  ordinal_position: number;
+  /**
+   * What the LLM saw / should see at this position. `null` when no
+   * system-layer override was set (only user-layer). Stored but inert
+   * at display time today.
+   */
+  system_override: string | null;
+  /**
+   * What the human sees in the chat transcript at this position.
+   * `null` when no user-layer override was set (only system-layer).
+   */
+  user_override: string | null;
+  /** ISO-8601 timestamp the override was first written. */
+  created_at: string;
+  /** ISO-8601 timestamp of the last update. */
+  updated_at: string;
+}
+
+/**
+ * Projects a `MessageOverrideRow` to the snake_case wire shape. Kept here
+ * (not in `db/schema.ts`) so the route file owns its own wire contract.
+ */
+function overrideRowToView(row: typeof messageOverride.$inferSelect): MessageOverrideView {
+  return {
+    ordinal_position: row.ordinalPosition,
+    system_override: row.systemOverride,
+    user_override: row.userOverride,
+    created_at: row.createdAt,
+    updated_at: row.updatedAt,
+  };
+}
+
+/**
+ * `GET /sessions/:id/message-overrides` — list the caller's overrides for
+ * the session's underlying Letta conversation.
+ *
+ * Returns the rows sorted by `ordinal_position` ascending so consumers
+ * can render them alongside the message list at the matching index. An
+ * empty list (no overrides set) returns `{ overrides: [] }` with 200.
+ *
+ * Owner-scoped: 404 for sessions the caller doesn't own.
+ */
+export const handleListMessageOverrides: RouteHandler = protectedRoute(
+  {},
+  async (_req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    const row = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!row || row.userId !== auth.user.id) return notFound();
+
+    const rows = ctx.db
+      .select()
+      .from(messageOverride)
+      .where(eq(messageOverride.conversationId, row.lettaConversationId))
+      .orderBy(messageOverride.ordinalPosition)
+      .all();
+    return jsonResponse(200, { overrides: rows.map(overrideRowToView) });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  PUT /sessions/:id/message-overrides/:position                             */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Body for `PUT /sessions/:id/message-overrides/:position`. */
+const putMessageOverrideSchema = z
+  .object({
+    /**
+     * What the LLM saw / should see at this position. Stored but inert
+     * at display today. Empty string is valid.
+     */
+    system_override: z.string().optional(),
+    /**
+     * What the human sees in the chat transcript at this position. Empty
+     * string is valid — it hides the message visually but keeps the bubble
+     * slot. Callers that want to remove the slot entirely use `DELETE`.
+     */
+    user_override: z.string().optional(),
+  })
+  .strict()
+  .refine(
+    (b) => b.system_override !== undefined || b.user_override !== undefined,
+    {
+      message: "At least one of `system_override` or `user_override` must be set.",
+    },
+  );
+
+/**
+ * `PUT /sessions/:id/message-overrides/:position` — upsert one or both
+ * override layers for the message at `position`.
+ *
+ * **Validation gates** (in order):
+ * - `404` — session not owned by caller (or doesn't exist).
+ * - `400 invalid_position` — path segment doesn't parse as a non-negative
+ *   integer.
+ * - `400 validation` — body missing both fields.
+ * - `409 turn_in_progress` — a `turn` row exists with `status = "running"`
+ *   for this session. Honoring writes while a turn is in flight would
+ *   race the post-turn writer, so we reject up front.
+ * - `409 message_not_found` — `position` is out of range for the current
+ *   Letta message list. The override would point at a message that
+ *   doesn't exist; callers must wait for the message to land before
+ *   overriding it.
+ *
+ * **Merge semantics.** Only the layers the body provides are written; an
+ * existing value on the other layer is preserved by reading the row,
+ * computing the merged tuple, and upserting the result. This lets the
+ * `/chat` post-turn writer set `user_override` (leaving `system_override`
+ * null) and a later operator PUT set `system_override` without
+ * clobbering the post-turn-written `user_override`.
+ *
+ * Idempotent: same body → same result. Returns 200 with the resulting view.
+ */
+export const handlePutMessageOverride: RouteHandler = protectedRoute(
+  {},
+  async (req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    const positionStr = params.position;
+    if (!positionStr) return notFound();
+    const position = Number.parseInt(positionStr, 10);
+    if (!Number.isInteger(position) || position < 0 || String(position) !== positionStr) {
+      return validationError(
+        "ordinal_position must be a non-negative integer.",
+        "invalid_position",
+      );
+    }
+
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = putMessageOverrideSchema.safeParse(raw);
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      return validationError(issue?.message ?? "Invalid request body.");
+    }
+    const { system_override: systemOverride, user_override: userOverride } = parsed.data;
+
+    const row = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!row || row.userId !== auth.user.id) return notFound();
+
+    // Gate 1: no live turn for this session. Avoids racing the post-turn
+    // writer (`/chat`) and keeps the invariant "messages we override
+    // already exist in Letta and aren't moving."
+    const liveTurn = ctx.db
+      .select({ id: turn.id })
+      .from(turn)
+      .where(and(eq(turn.sessionId, id), eq(turn.status, "running")))
+      .get();
+    if (liveTurn) {
+      return conflictError(
+        "turn_in_progress",
+        "Cannot modify message overrides while a turn is in progress.",
+      );
+    }
+
+    // Gate 2: target position must exist in Letta's message list. The
+    // listMessages count is the position-space size; `position < count`
+    // is the existence condition.
+    let lettaMessages: ReadonlyArray<LettaMessage>;
+    try {
+      lettaMessages = await ctx.lettaClient.listMessages(row.lettaConversationId);
+    } catch (err) {
+      ctx.logger.error(
+        {
+          event: "message_override_letta_list_failed",
+          session_id: id,
+          letta_conversation_id: row.lettaConversationId,
+          err: err instanceof Error ? err.message : String(err),
+        },
+        "Letta listMessages failed during override validation.",
+      );
+      return internalError("Failed to validate message position against Letta.");
+    }
+    if (position >= lettaMessages.length) {
+      return conflictError(
+        "message_not_found",
+        `No Letta message exists at position ${position} (conversation has ${lettaMessages.length}).`,
+      );
+    }
+
+    // Merge: read existing row (if any), preserve untouched layer.
+    const existing = ctx.db
+      .select()
+      .from(messageOverride)
+      .where(
+        and(
+          eq(messageOverride.conversationId, row.lettaConversationId),
+          eq(messageOverride.ordinalPosition, position),
+        ),
+      )
+      .get();
+    const merged: { systemOverride: string | null; userOverride: string | null } = {
+      systemOverride: systemOverride !== undefined ? systemOverride : existing?.systemOverride ?? null,
+      userOverride: userOverride !== undefined ? userOverride : existing?.userOverride ?? null,
+    };
+    // CHECK constraint is enforced in SQL too, but explicit guard keeps
+    // the error surface clean (caller saw a 400 already if both were
+    // omitted on the wire; this catches the "you cleared both" edge).
+    if (merged.systemOverride === null && merged.userOverride === null) {
+      return validationError(
+        "Resulting override would have both layers null. At least one must be non-null.",
+      );
+    }
+
+    const now = nowIso();
+    ctx.db
+      .insert(messageOverride)
+      .values({
+        conversationId: row.lettaConversationId,
+        ordinalPosition: position,
+        systemOverride: merged.systemOverride,
+        userOverride: merged.userOverride,
+        createdAt: now,
+        updatedAt: now,
+      })
+      .onConflictDoUpdate({
+        target: [messageOverride.conversationId, messageOverride.ordinalPosition],
+        set: {
+          systemOverride: merged.systemOverride,
+          userOverride: merged.userOverride,
+          updatedAt: now,
+        },
+      })
+      .run();
+    const fresh = ctx.db
+      .select()
+      .from(messageOverride)
+      .where(
+        and(
+          eq(messageOverride.conversationId, row.lettaConversationId),
+          eq(messageOverride.ordinalPosition, position),
+        ),
+      )
+      .get();
+    if (!fresh) {
+      return internalError("Failed to persist message override.");
+    }
+    ctx.logger.info(
+      {
+        event: "message_override_upserted",
+        user_id: auth.user.id,
+        session_id: id,
+        ordinal_position: position,
+        layers_written: {
+          system_override: systemOverride !== undefined,
+          user_override: userOverride !== undefined,
+        },
+      },
+      "Message override upserted.",
+    );
+    return jsonResponse(200, overrideRowToView(fresh));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  DELETE /sessions/:id/message-overrides/:position                          */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `DELETE /sessions/:id/message-overrides/:position` — remove an override.
+ *
+ * Idempotent: returns 204 whether or not the row existed. Owner-scoped:
+ * 404 for sessions the caller doesn't own.
+ */
+export const handleDeleteMessageOverride: RouteHandler = protectedRoute(
+  {},
+  async (_req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    const positionStr = params.position;
+    if (!positionStr) return notFound();
+    const position = Number.parseInt(positionStr, 10);
+    if (!Number.isInteger(position) || position < 0 || String(position) !== positionStr) {
+      return validationError(
+        "ordinal_position must be a non-negative integer.",
+        "invalid_position",
+      );
+    }
+    const row = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!row || row.userId !== auth.user.id) return notFound();
+
+    ctx.db
+      .delete(messageOverride)
+      .where(
+        and(
+          eq(messageOverride.conversationId, row.lettaConversationId),
+          eq(messageOverride.ordinalPosition, position),
+        ),
+      )
+      .run();
+    return new Response(null, { status: 204 });
+  },
+);
+
+/**
+ * Per-id aggregate built by `collectAggregates` from sibling Letta
+ * message rows. Attached to the surviving assistant_message during the
+ * projection pass.
+ */
+interface TurnAggregate {
+  /** Concatenated reasoning text across every reasoning_message row. */
+  reasoning: string;
+  /**
+   * Tool calls invoked during the turn — one entry per `tool_call_id`,
+   * paired with its matching `tool_return_message` when present.
+   */
+  toolCalls: AIHubToolCallRecord[];
+}
+
+/**
+ * One Letta agent run that produced reasoning / tool calls but never
+ * emitted an `assistant_message`. Some agents fulfill the whole task
+ * via tools and never send text back to the user (verified against
+ * real Letta data — a 29-step agent doing shell + file work surfaces
+ * 0 assistant_message rows). The projector synthesizes a virtual
+ * assistant bubble per orphan run so ai-hub shows the same activity
+ * Letta's ADE shows.
+ */
+interface OrphanRun {
+  /** Letta run id — used as the synthetic message id seed. */
+  runId: string;
+  /** ISO date of the latest row in this run, for sort ordering. */
+  latestDate: string;
+  /** Reasoning + tool calls accumulated across the run's steps. */
+  aggregate: TurnAggregate;
+}
+
+/**
+ * Combined return shape of `collectAggregates`. The caller uses
+ * `byAssistantId` for the normal projector merge and `orphanRuns` for
+ * the synthesize-a-bubble path.
+ */
+interface CollectedAggregates {
+  /**
+   * Map of `assistant_message.id` → aggregate. Used by the normal
+   * projector pass to attach reasoning + tool calls to an existing
+   * assistant bubble.
+   */
+  byAssistantId: Map<string, TurnAggregate>;
+  /**
+   * Runs that produced affordances but no `assistant_message`. The
+   * caller synthesizes one virtual assistant bubble per entry.
+   */
+  orphanRuns: OrphanRun[];
+}
+
+/** A pending tool-call record with its sort order and optional result. */
+interface PendingToolCall {
+  order: number;
+  name: string;
+  input: string;
+  result?: {
+    output?: string | null;
+    error?: string | null;
+    status: "success" | "error";
+  };
+}
+
+/**
+ * Builds, per `assistant_message` id, the aggregate of reasoning +
+ * tool-call records that the React client renders inside that bubble.
+ *
+ * **Strategy — group by Letta's `run_id`.** Every row Letta returns
+ * from `messages.list` carries a `run_id` that identifies the agent
+ * run (and a `step_id` for the specific step). All rows of one
+ * logical turn share a `run_id` regardless of how Letta stamps the
+ * outer `id`. We use that as the primary grouping key:
+ *
+ * 1. Scan every row, bucketing reasoning + tool-call contributions by
+ *    `run_id`.
+ * 2. For each `assistant_message` row, look up its `run_id` and attach
+ *    that bucket's contents to the assistant's id.
+ *
+ * Fallback layers (kept for robustness against older Letta versions
+ * that may omit `run_id`):
+ *
+ * - **Same outer-`id` grouping.** When rows share the assistant's
+ *   outer `id` (single-step run, no `run_id`), match by id.
+ * - **Chronological turn-walk.** Walk in date order; reset at
+ *   `user_message` boundaries; on `assistant_message`, attach the
+ *   buffered contributions to that id.
+ *
+ * Per assistant id we union the contributions of all three layers,
+ * deduping tool calls by inner `tool_call_id`.
+ *
+ * Callers MUST pass `messages` sorted ascending by `date`.
+ *
+ * @param messages - rows from `client.conversations.messages.list`,
+ *   sorted ascending by `date`.
+ * @returns map of `assistant_message.id` → aggregate.
+ */
+function collectAggregates(
+  messages: ReadonlyArray<LettaMessage>,
+): CollectedAggregates {
+  // Layer 1 (primary): by Letta's run_id.
+  const reasoningByRun = new Map<string, string>();
+  const callsByRun = new Map<string, Map<string, PendingToolCall>>();
+  const callOrderByRun = new Map<string, number>();
+  // Layer 2 (fallback): by outer message id.
+  const reasoningById = new Map<string, string>();
+  const callsById = new Map<string, Map<string, PendingToolCall>>();
+  const callOrderById = new Map<string, number>();
+  // Layer 3 (fallback): chronological turn-walk.
+  const turnReasoningByAssistant = new Map<string, string>();
+  const turnCallsByAssistant = new Map<
+    string,
+    Map<string, PendingToolCall>
+  >();
+
+  // run_id → set of assistant_message ids (typically size 1 for a
+  // straightforward turn; size > 1 when an agent run produces multiple
+  // distinct assistant rows — we attach the aggregate to ALL of them so
+  // every visible bubble gets the affordance data).
+  const assistantIdsByRun = new Map<string, Set<string>>();
+  // run_id → latest ISO date observed for any row in that run. Used
+  // for sort placement when we synthesize a virtual bubble for an
+  // orphan run (no assistant_message ever emitted).
+  const latestDateByRun = new Map<string, string>();
+  function noteRunDate(runId: string, date: string | undefined): void {
+    if (!date) return;
+    const prev = latestDateByRun.get(runId);
+    if (!prev || prev < date) {
+      latestDateByRun.set(runId, date);
+    }
+  }
+
+  // Chronological-walk buffer.
+  let bufferReasoning = "";
+  const bufferCalls = new Map<string, PendingToolCall>();
+  let bufferOrder = 0;
+
+  function resetBuffer(): void {
+    bufferReasoning = "";
+    bufferCalls.clear();
+    bufferOrder = 0;
+  }
+
+  function flushBufferToAssistant(id: string): void {
+    if (bufferReasoning.length > 0) {
+      turnReasoningByAssistant.set(id, bufferReasoning);
+    }
+    if (bufferCalls.size > 0) {
+      const copy = new Map<string, PendingToolCall>();
+      for (const [k, v] of bufferCalls.entries()) copy.set(k, { ...v });
+      turnCallsByAssistant.set(id, copy);
+    }
+    resetBuffer();
+  }
+
+  function bumpOrder(map: Map<string, number>, key: string): number {
+    const next = (map.get(key) ?? 0) + 1;
+    map.set(key, next);
+    return next;
+  }
+
+  function ensureBucket<K>(
+    map: Map<K, Map<string, PendingToolCall>>,
+    key: K,
+  ): Map<string, PendingToolCall> {
+    let b = map.get(key);
+    if (!b) {
+      b = new Map<string, PendingToolCall>();
+      map.set(key, b);
+    }
+    return b;
+  }
+
+  function addInputToBucket(
+    bucket: Map<string, PendingToolCall>,
+    callId: string,
+    call: {
+      name?: string | null;
+      arguments?: string | null;
+    },
+    nextOrder: () => number,
+  ): void {
+    const prev = bucket.get(callId);
+    if (prev) {
+      // Letta persists multi-chunk tool_call_message rows where each
+      // row carries the **accumulated** args (not a true delta — `row1
+      // = "{"`; `row2 = "{"command":"`; `rowN = "{...}"`). Naive `+=`
+      // concatenation duplicates the args N times, producing
+      // `{...}{...}{...}` in the rendered tool card. The right
+      // primitive is "keep the longest args we've seen": for a true
+      // accumulation Letta produces, the last row is the longest; for
+      // repeated identical rows the length comparison is a no-op.
+      const incoming = call.arguments ?? "";
+      if (incoming.length > prev.input.length) {
+        prev.input = incoming;
+      }
+      if (call.name && !prev.name) prev.name = call.name;
+    } else {
+      bucket.set(callId, {
+        order: nextOrder(),
+        name: call.name ?? "",
+        input: call.arguments ?? "",
+      });
+    }
+  }
+
+  function addResultToBucket(
+    bucket: Map<string, PendingToolCall>,
+    callId: string,
+    result: {
+      output?: string | null;
+      error?: string | null;
+      status: "success" | "error";
+    },
+    nextOrder: () => number,
+  ): void {
+    const prev = bucket.get(callId);
+    if (prev) {
+      prev.result = result;
+    } else {
+      bucket.set(callId, {
+        order: nextOrder(),
+        name: "",
+        input: "",
+        result,
+      });
+    }
+  }
+
+  for (const raw of messages) {
+    const m = raw as {
+      id?: string;
+      run_id?: string | null;
+      date?: string;
+      message_type?: string;
+      reasoning?: string;
+      tool_call?: {
+        tool_call_id?: string | null;
+        name?: string | null;
+        arguments?: string | null;
+      } | null;
+      tool_calls?:
+        | ReadonlyArray<{
+            tool_call_id?: string | null;
+            name?: string | null;
+            arguments?: string | null;
+          }>
+        | { tool_call_id?: string | null; name?: string | null; arguments?: string | null }
+        | null;
+      tool_call_id?: string;
+      tool_return?: string | Array<unknown>;
+      status?: "success" | "error";
+      tool_returns?: Array<{
+        tool_call_id?: string;
+        status?: "success" | "error";
+        tool_return?: string | Array<unknown>;
+      }> | null;
+    };
+
+    const runId = m.run_id ?? null;
+    if (runId) noteRunDate(runId, m.date);
+
+    if (m.message_type === "user_message") {
+      // User boundary resets the chronological buffer (other layers are
+      // run-id / outer-id-keyed, so they don't need a reset).
+      resetBuffer();
+      continue;
+    }
+
+    if (m.message_type === "reasoning_message") {
+      const text = typeof m.reasoning === "string" ? m.reasoning : "";
+      if (text.length === 0) continue;
+      bufferReasoning += text;
+      if (m.id) {
+        reasoningById.set(m.id, (reasoningById.get(m.id) ?? "") + text);
+      }
+      if (runId) {
+        reasoningByRun.set(runId, (reasoningByRun.get(runId) ?? "") + text);
+      }
+      continue;
+    }
+
+    if (m.message_type === "tool_call_message") {
+      const list = Array.isArray(m.tool_calls)
+        ? m.tool_calls
+        : m.tool_calls && typeof m.tool_calls === "object"
+          ? [m.tool_calls]
+          : m.tool_call
+            ? [m.tool_call]
+            : [];
+      for (const call of list) {
+        const callId = call.tool_call_id;
+        if (!callId) continue;
+        addInputToBucket(bufferCalls, callId, call, () => bufferOrder++);
+        if (m.id) {
+          addInputToBucket(
+            ensureBucket(callsById, m.id),
+            callId,
+            call,
+            () => bumpOrder(callOrderById, m.id ?? ""),
+          );
+        }
+        if (runId) {
+          addInputToBucket(
+            ensureBucket(callsByRun, runId),
+            callId,
+            call,
+            () => bumpOrder(callOrderByRun, runId),
+          );
+        }
+      }
+      continue;
+    }
+
+    if (m.message_type === "tool_return_message") {
+      const returns = Array.isArray(m.tool_returns)
+        ? m.tool_returns
+        : m.tool_call_id
+          ? [
+              {
+                tool_call_id: m.tool_call_id,
+                status: m.status,
+                tool_return: m.tool_return,
+              },
+            ]
+          : [];
+      for (const ret of returns) {
+        const callId = ret.tool_call_id;
+        if (!callId) continue;
+        const status: "success" | "error" =
+          ret.status === "error" ? "error" : "success";
+        const text = stringifyReturn(ret.tool_return);
+        const result =
+          status === "error"
+            ? { error: text, output: null, status }
+            : { output: text, error: null, status };
+        addResultToBucket(bufferCalls, callId, result, () => bufferOrder++);
+        if (m.id) {
+          addResultToBucket(
+            ensureBucket(callsById, m.id),
+            callId,
+            result,
+            () => bumpOrder(callOrderById, m.id ?? ""),
+          );
+        }
+        if (runId) {
+          addResultToBucket(
+            ensureBucket(callsByRun, runId),
+            callId,
+            result,
+            () => bumpOrder(callOrderByRun, runId),
+          );
+        }
+      }
+      continue;
+    }
+
+    if (m.message_type === "assistant_message") {
+      const id = m.id;
+      if (!id) {
+        resetBuffer();
+        continue;
+      }
+      flushBufferToAssistant(id);
+      if (runId) {
+        let set = assistantIdsByRun.get(runId);
+        if (!set) {
+          set = new Set();
+          assistantIdsByRun.set(runId, set);
+        }
+        set.add(id);
+      }
+      continue;
+    }
+  }
+
+  // ── Union per assistant id: layer 1 (run_id) ∪ layer 2 (same id) ∪
+  //    layer 3 (chronological). Tool calls dedupe by tool_call_id.
+  const out = new Map<string, TurnAggregate>();
+  const allAssistantIds = new Set<string>([
+    ...turnReasoningByAssistant.keys(),
+    ...turnCallsByAssistant.keys(),
+    ...reasoningById.keys(),
+    ...callsById.keys(),
+  ]);
+  // Also pull in assistant ids that only the run_id layer surfaces.
+  for (const set of assistantIdsByRun.values()) {
+    for (const id of set) allAssistantIds.add(id);
+  }
+
+  // Inverse map for run_id lookup from assistant id.
+  const runIdByAssistant = new Map<string, string>();
+  for (const [run, set] of assistantIdsByRun.entries()) {
+    for (const id of set) runIdByAssistant.set(id, run);
+  }
+
+  for (const id of allAssistantIds) {
+    const runId = runIdByAssistant.get(id);
+    // **Reasoning attribution** (multi-step turns): the chronological
+    // turn-walk is the *authoritative* source. It partitions reasoning
+    // text per assistant_message via `flushBufferToAssistant`, so each
+    // bubble carries only the reasoning that arrived between the
+    // previous boundary and its own assistant_message. The `id`-keyed
+    // and `run_id`-keyed layers are NOT siblings the way `??` would
+    // imply — `reasoningByRun` holds the run's *concatenated*
+    // reasoning across every step, so using it as a fallback for
+    // bubbles that have no per-step reasoning (e.g. the agent only
+    // reasoned in step 1 but produced 5 assistant messages) attaches
+    // step 1's text to every bubble in the run. The id/run layers
+    // remain as last-resort fallbacks for orphan-ish cases where the
+    // chronological walk found nothing AND there's exactly one
+    // assistant_message in the run (the single-step case where the
+    // by-run aggregate is unambiguously this bubble's reasoning).
+    const layer3Reasoning = turnReasoningByAssistant.get(id);
+    let reasoning: string;
+    if (layer3Reasoning !== undefined) {
+      reasoning = layer3Reasoning;
+    } else {
+      const idReasoning = reasoningById.get(id);
+      const runReasoning =
+        runId !== undefined ? reasoningByRun.get(runId) : undefined;
+      // Only trust the run-level reasoning when the run has exactly one
+      // assistant_message — otherwise we'd attach concatenated
+      // multi-step reasoning to a bubble that didn't produce any.
+      const runAssistantCount =
+        runId !== undefined
+          ? (assistantIdsByRun.get(runId)?.size ?? 0)
+          : 0;
+      reasoning =
+        idReasoning ?? (runAssistantCount === 1 ? (runReasoning ?? "") : "");
+    }
+
+    const merged = new Map<string, PendingToolCall>();
+    const mergeBucket = (
+      bucket: Map<string, PendingToolCall> | undefined,
+    ): void => {
+      if (!bucket) return;
+      for (const [callId, info] of bucket.entries()) {
+        const prev = merged.get(callId);
+        if (!prev) {
+          merged.set(callId, { ...info });
+          continue;
+        }
+        if (!prev.name && info.name) prev.name = info.name;
+        if (!prev.input && info.input) prev.input = info.input;
+        if (!prev.result && info.result) prev.result = info.result;
+      }
+    };
+    // **Tool-call attribution** (multi-step turns): same problem as
+    // reasoning. The chronological turn-walk (`turnCallsByAssistant`)
+    // partitions tool calls per assistant_message — that's
+    // authoritative for the common multi-step shape Letta produces
+    // (reasoning → tool → return → assistant text, repeat). The
+    // `callsByRun` layer holds ALL tools in the run, so using it as a
+    // sibling source attaches every step's tools to every bubble (the
+    // bug). We use the chronological walk as the **exclusive** source
+    // when it has any tools for this assistant id; the `id`-keyed and
+    // `runId`-keyed layers are pure fallbacks for the orphan-ish cases
+    // where the chronological walk found nothing (e.g. tools arriving
+    // after their owning assistant_message in pathological orderings).
+    const layer3 = turnCallsByAssistant.get(id);
+    if (layer3 && layer3.size > 0) {
+      mergeBucket(layer3);
+    } else {
+      mergeBucket(callsById.get(id));
+      if (runId) mergeBucket(callsByRun.get(runId));
+    }
+
+    const calls: AIHubToolCallRecord[] = [...merged.entries()]
+      .sort(([, a], [, b]) => a.order - b.order)
+      .map(([callId, info]): AIHubToolCallRecord => {
+        const result = info.result;
+        if (result) {
+          return {
+            tool_call_id: callId,
+            tool_name: info.name,
+            input: info.input,
+            status: result.status,
+            output: result.output ?? null,
+            error: result.error ?? null,
+          };
+        }
+        return {
+          tool_call_id: callId,
+          tool_name: info.name,
+          input: info.input,
+          status: "error",
+          output: null,
+          error: "Tool call has no recorded return.",
+        };
+      });
+
+    if (reasoning.length > 0 || calls.length > 0) {
+      out.set(id, { reasoning, toolCalls: calls });
+    }
+  }
+
+  // ── Orphan runs: agent runs that produced reasoning / tool calls
+  //    but never emitted an assistant_message. Build a separate entry
+  //    per run_id; the caller synthesizes a virtual assistant bubble
+  //    so the activity is visible in the chat (some agents fulfill the
+  //    whole task via tools — verified against real Letta data).
+  const orphanRuns: OrphanRun[] = [];
+  for (const [runId, latestDate] of latestDateByRun.entries()) {
+    if (assistantIdsByRun.has(runId)) continue;
+    const reasoning = reasoningByRun.get(runId) ?? "";
+    const callsBucket = callsByRun.get(runId);
+    if (reasoning.length === 0 && (!callsBucket || callsBucket.size === 0)) {
+      continue;
+    }
+    const calls: AIHubToolCallRecord[] = callsBucket
+      ? [...callsBucket.entries()]
+          .sort(([, a], [, b]) => a.order - b.order)
+          .map(([callId, info]): AIHubToolCallRecord => {
+            const result = info.result;
+            if (result) {
+              return {
+                tool_call_id: callId,
+                tool_name: info.name,
+                input: info.input,
+                status: result.status,
+                output: result.output ?? null,
+                error: result.error ?? null,
+              };
+            }
+            return {
+              tool_call_id: callId,
+              tool_name: info.name,
+              input: info.input,
+              status: "error",
+              output: null,
+              error: "Tool call has no recorded return.",
+            };
+          })
+      : [];
+    orphanRuns.push({
+      runId,
+      latestDate,
+      aggregate: { reasoning, toolCalls: calls },
+    });
+  }
+  // Sort orphan runs by latestDate ascending so they slot into the
+  // wire list in the right chronological position.
+  orphanRuns.sort((a, b) =>
+    a.latestDate < b.latestDate ? -1 : a.latestDate > b.latestDate ? 1 : 0,
+  );
+
+  return { byAssistantId: out, orphanRuns };
+}
+
+/**
+ * Pretty-prints a tool-return value into a string the UI can render in
+ * a `<pre>`. Letta's `tool_return` can be a string OR an array of
+ * content parts; arrays collapse into JSON for visibility.
+ */
+function stringifyReturn(value: string | Array<unknown> | undefined | null): string {
+  if (typeof value === "string") return value;
+  if (value == null) return "";
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * Projects one Letta `Message` into ai-hub's wire-shaped `AIHubMessage`.
+ *
+ * Letta's history is a discriminated union over a dozen variants; ai-hub
+ * surfaces the three the React client renders directly (user, assistant,
+ * system). Tool-call / tool-return / reasoning / approval messages are
+ * not rendered as standalone bubbles in v1 — the SSE stream weaves them
+ * into the assistant bubble via `tool_call_*` and `reasoning_delta`
+ * events at turn time, but the historical replay collapses them into the
+ * surrounding assistant text. Returning `null` from this projector means
+ * "skip this row" (filtered out by the caller).
+ *
+ * @param msg - one row from `client.conversations.messages.list`.
+ * @returns the wire-shaped message, or `null` if not surfaced in v1.
+ */
+function toWireMessage(msg: LettaMessage): AIHubMessage | null {
+  switch (msg.message_type) {
+    case "user_message":
+      return {
+        id: msg.id,
+        role: "user",
+        content: extractTextContent(msg.content),
+        created_at: msg.date,
+      };
+    case "assistant_message":
+      return {
+        id: msg.id,
+        role: "assistant",
+        content: extractTextContent(msg.content),
+        created_at: msg.date,
+      };
+    case "system_message":
+      return {
+        id: msg.id,
+        role: "system",
+        content: extractTextContent(msg.content),
+        created_at: msg.date,
+      };
+    default:
+      // reasoning_message / hidden_reasoning_message / tool_call_message /
+      // tool_return_message / approval_* / summary_message / event_message
+      // are not v1 history-render targets — see file-level comment.
+      return null;
+  }
+}
+
+/**
+ * Flattens a Letta message's content into a display string. Letta
+ * persists messages as either a plain string or a multi-modal array
+ * of `{type: "text", text}` parts; this normalizes both into a
+ * single string suitable for the chat-UI bubble.
+ *
+ * Along the way it strips `<system-reminder>…</system-reminder>`
+ * blocks that Letta Code injects at the head of every user turn
+ * (agent metadata + permission-mode notice). Those are useful to the
+ * LLM but pure noise in the chat transcript.
+ *
+ * Run on every role (user / assistant / system) so the strip is
+ * consistent regardless of where reminders end up.
+ */
+function extractTextContent(
+  content: string | Array<{ type?: string; text?: string }>,
+): string {
+  if (typeof content === "string") return stripSystemReminders(content);
+  if (!Array.isArray(content)) return "";
+  let out = "";
+  for (const part of content) {
+    if (part && (part.type === undefined || part.type === "text") && typeof part.text === "string") {
+      out += part.text;
+    }
+  }
+  return stripSystemReminders(out);
+}
+
+/**
+ * Strips `<system-reminder>…</system-reminder>` blocks (and the
+ * blank lines that typically trail them) from a user-facing string.
+ * Letta Code injects these blocks at the head of every user turn —
+ * harmless to the LLM but visible noise in chat history.
+ */
+function stripSystemReminders(text: string): string {
+  return text
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>\s*/g, "")
+    .replace(/^\s+/, "");
+}
+