@data-club/ai-hub-server 0.0.1

package/dist/routes/sessions.js

@@ -0,0 +1,1501 @@
+/**
+ * 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 { protectedRoute } from "../auth/middleware.js";
+import { agent, messageOverride, messageUsage, rotatingMessage, session, turn, } from "../db/schema.js";
+import { conflictError, internalError, jsonResponse, notFound, validationError, } from "../handlers/responses.js";
+import { ForkSourceNotFoundError } from "../letta/client.js";
+import { materializeSandbox, purgeSandbox, resolveSandboxDir, resolveSeedDir, } from "../letta/sandbox.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) {
+    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, extras) {
+    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() {
+    return new Date().toISOString();
+}
+/**
+ * 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, forkSourceConversationId) {
+    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 = protectedRoute({}, async (req, ctx, auth) => {
+    let raw;
+    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 = "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;
+    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;
+        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 = 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 = 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 = protectedRoute({}, async (req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id)
+        return notFound();
+    let raw;
+    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 = "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 = {
+            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 = protectedRoute({}, async (req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id)
+        return notFound();
+    let raw;
+    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 = { 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 = 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 = 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, row) {
+    const id = row.id;
+    let messages;
+    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, row, messages) {
+    // 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.date ?? "");
+        const bT = Date.parse(b.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);
+    const priority = {
+        assistant: 3,
+        user: 2,
+        system: 1,
+        tool: 0,
+    };
+    const dedupedById = new Map();
+    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 = projected;
+        if (projected.role === "assistant") {
+            const agg = aggregates.get(projected.id);
+            if (agg) {
+                const next = { ...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 = {
+            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();
+    sortedRaw.forEach((raw, idx) => {
+        const id = raw.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();
+    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();
+    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) => {
+        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 });
+}
+/**
+ * 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) {
+    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 = 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 = 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;
+    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;
+    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: 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 = 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 });
+});
+/**
+ * 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) {
+    // Layer 1 (primary): by Letta's run_id.
+    const reasoningByRun = new Map();
+    const callsByRun = new Map();
+    const callOrderByRun = new Map();
+    // Layer 2 (fallback): by outer message id.
+    const reasoningById = new Map();
+    const callsById = new Map();
+    const callOrderById = new Map();
+    // Layer 3 (fallback): chronological turn-walk.
+    const turnReasoningByAssistant = new Map();
+    const turnCallsByAssistant = new Map();
+    // 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();
+    // 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();
+    function noteRunDate(runId, date) {
+        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();
+    let bufferOrder = 0;
+    function resetBuffer() {
+        bufferReasoning = "";
+        bufferCalls.clear();
+        bufferOrder = 0;
+    }
+    function flushBufferToAssistant(id) {
+        if (bufferReasoning.length > 0) {
+            turnReasoningByAssistant.set(id, bufferReasoning);
+        }
+        if (bufferCalls.size > 0) {
+            const copy = new Map();
+            for (const [k, v] of bufferCalls.entries())
+                copy.set(k, { ...v });
+            turnCallsByAssistant.set(id, copy);
+        }
+        resetBuffer();
+    }
+    function bumpOrder(map, key) {
+        const next = (map.get(key) ?? 0) + 1;
+        map.set(key, next);
+        return next;
+    }
+    function ensureBucket(map, key) {
+        let b = map.get(key);
+        if (!b) {
+            b = new Map();
+            map.set(key, b);
+        }
+        return b;
+    }
+    function addInputToBucket(bucket, callId, call, nextOrder) {
+        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, callId, result, nextOrder) {
+        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;
+        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 = 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();
+    const allAssistantIds = new Set([
+        ...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();
+    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;
+        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();
+        const mergeBucket = (bucket) => {
+            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 = [...merged.entries()]
+            .sort(([, a], [, b]) => a.order - b.order)
+            .map(([callId, info]) => {
+            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 = [];
+    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 = callsBucket
+            ? [...callsBucket.entries()]
+                .sort(([, a], [, b]) => a.order - b.order)
+                .map(([callId, info]) => {
+                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) {
+    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) {
+    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) {
+    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) {
+    return text
+        .replace(/<system-reminder>[\s\S]*?<\/system-reminder>\s*/g, "")
+        .replace(/^\s+/, "");
+}
+//# sourceMappingURL=sessions.js.map