chore(release): v1.27.1

chore: release tokens
chore: relicense to AGPL-3.0-or-later
2026-03-29 17:57:29 +00:00 · 2026-03-29 01:15:38 +00:00 · 2026-03-29 01:13:13 +00:00 · 2026-03-29 00:57:09 +00:00 · 2026-03-27 10:38:00 +00:00 · 2026-03-23 20:14:15 +03:00
41 changed files with 3536 additions and 3134 deletions
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      increment:
+        description: 'Version bump: patch, minor, major, or explicit (e.g. 1.27.0)'
+        required: true
+        default: 'patch'
+        type: string
+      release_name:
+        description: 'Custom release name (optional, defaults to "CloudCLI UI vX.Y.Z")'
+        required: false
+        type: string
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_PAT }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: git config
+        run: |
+          git config user.name "${GITHUB_ACTOR}"
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+
+      - run: npm ci
+
+      - name: Release
+        run: |
+          ARGS="--ci --increment=${{ inputs.increment }}"
+          if [ -n "${{ inputs.release_name }}" ]; then
+            ARGS="$ARGS --github.releaseName=\"${{ inputs.release_name }}\""
+          fi
+          npx release-it $ARGS
+        env:
+          GITHUB_TOKEN: ${{ secrets.RELEASE_PAT }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,51 @@
 All notable changes to CloudCLI UI will be documented in this file.


+## [1.27.1](https://github.com/siteboon/claudecodeui/compare/v1.26.3...v1.27.1) (2026-03-29)
+
+### Bug Fixes
+
+* prevent split on undefined（[#491](https://github.com/siteboon/claudecodeui/issues/491)） ([#563](https://github.com/siteboon/claudecodeui/issues/563)) ([b54cdf8](https://github.com/siteboon/claudecodeui/commit/b54cdf8168fc224e9907796e4229ae8ed34e6885))
+
+### Maintenance
+
+* add release-it github action ([42a1313](https://github.com/siteboon/claudecodeui/commit/42a131389a6954df0d2c3bedd2cb6d3406c5ebc1))
+* add terminal plugin in the plugins list ([004135e](https://github.com/siteboon/claudecodeui/commit/004135ef0187023e1da29c4a7137a28a42ebf9af))
+* release tokens ([f1063fd](https://github.com/siteboon/claudecodeui/commit/f1063fd33964ccb517f5ebcdd14526ed162e1138))
+* relicense to AGPL-3.0-or-later ([27cd124](https://github.com/siteboon/claudecodeui/commit/27cd12432b7d3237981f86acd9cc99532d843d4a))
+
+## [1.26.3](https://github.com/siteboon/claudecodeui/compare/v1.26.2...v1.26.3) (2026-03-22)
+
+## [1.26.2](https://github.com/siteboon/claudecodeui/compare/v1.26.0...v1.26.2) (2026-03-21)
+
+### Bug Fixes
+
+* change SW cache mechanism ([17d6ec5](https://github.com/siteboon/claudecodeui/commit/17d6ec54af18d333c8b04d2ffc64793e688d996e))
+* claude auth changes and adding copy on mobile ([a41d2c7](https://github.com/siteboon/claudecodeui/commit/a41d2c713e87d56f23d5884585b4bb43c43a250a))
+
+## [1.26.0](https://github.com/siteboon/claudecodeui/compare/v1.25.2...v1.26.0) (2026-03-20)
+
+### New Features
+
+* add German (Deutsch) language support ([#525](https://github.com/siteboon/claudecodeui/issues/525)) ([a7299c6](https://github.com/siteboon/claudecodeui/commit/a7299c68237908c752d504c2e8eea91570a30203))
+* add WebSocket proxy for plugin backends ([#553](https://github.com/siteboon/claudecodeui/issues/553)) ([88c60b7](https://github.com/siteboon/claudecodeui/commit/88c60b70b031798d51ce26c8f080a0f64d824b05))
+* Browser autofill support for login form ([#521](https://github.com/siteboon/claudecodeui/issues/521)) ([72ff134](https://github.com/siteboon/claudecodeui/commit/72ff134b315b7a1d602f3cc7dd60d47c1c1c34af))
+* git panel redesign ([#535](https://github.com/siteboon/claudecodeui/issues/535)) ([adb3a06](https://github.com/siteboon/claudecodeui/commit/adb3a06d7e66a6d2dbcdfb501615e617178314af))
+* introduce notification system and claude notifications ([#450](https://github.com/siteboon/claudecodeui/issues/450)) ([45e71a0](https://github.com/siteboon/claudecodeui/commit/45e71a0e73b368309544165e4dcf8b7fd014e8dd))
+* **refactor:** move plugins to typescript ([#557](https://github.com/siteboon/claudecodeui/issues/557)) ([612390d](https://github.com/siteboon/claudecodeui/commit/612390db536417e2f68c501329bfccf5c6795e45))
+* unified message architecture with provider adapters and session store ([#558](https://github.com/siteboon/claudecodeui/issues/558)) ([a4632dc](https://github.com/siteboon/claudecodeui/commit/a4632dc4cec228a8febb7c5bae4807c358963678))
+
+### Bug Fixes
+
+* detect Claude auth from settings env ([#527](https://github.com/siteboon/claudecodeui/issues/527)) ([95bcee0](https://github.com/siteboon/claudecodeui/commit/95bcee0ec459f186d52aeffe100ac1a024e92909))
+* remove /exit command from claude login flow during onboarding ([#552](https://github.com/siteboon/claudecodeui/issues/552)) ([4de8b78](https://github.com/siteboon/claudecodeui/commit/4de8b78c6db5d8c2c402afce0f0b4cc16d5b6496))
+
+### Documentation
+
+* add German language link to all README files ([#534](https://github.com/siteboon/claudecodeui/issues/534)) ([1d31c3e](https://github.com/siteboon/claudecodeui/commit/1d31c3ec8309b433a041f3099955addc8c136c35))
+* **readme:** hotfix and improve for README.jp.md ([#550](https://github.com/siteboon/claudecodeui/issues/550)) ([7413c2c](https://github.com/siteboon/claudecodeui/commit/7413c2c78422c308ac949e6a83c3e9216b24b649))
+* **README:** update translations with CloudCLI branding and feature restructuring ([#544](https://github.com/siteboon/claudecodeui/issues/544)) ([14aef73](https://github.com/siteboon/claudecodeui/commit/14aef73cc6085fbb519fe64aea7cac80b7d51285))
+
 ## [1.25.2](https://github.com/siteboon/claudecodeui/compare/v1.25.0...v1.25.2) (2026-03-11)

 ### New Features
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -153,4 +153,4 @@ This automatically:

 ## License

-By contributing, you agree that your contributions will be licensed under the [GPL-3.0 License](LICENSE).
+By contributing, you agree that your contributions will be licensed under the [AGPL-3.0-or-later License](LICENSE), including the additional terms specified in Section 7 of the LICENSE file.
--- a/789
+++ b/789
--- a/13
+++ b/13
@@ -0,0 +1,13 @@
+CloudCLI UI
+Copyright 2025-2026 Siteboon AI B.V. and contributors
+
+This software is licensed under the GNU Affero General Public License v3.0
+or later (AGPL-3.0-or-later). See the LICENSE file for the full license text,
+including additional terms under Section 7.
+
+Originally developed by Siteboon AI B.V. (https://github.com/siteboon/claudecodeui).
+
+Contributions by Siteboon AI B.V. prior to commit 004135ef were originally
+published under GPL-3.0 and are hereby relicensed to AGPL-3.0-or-later.
+Contributions by other authors prior to that commit remain under GPL-3.0
+and are incorporated into this work as permitted by GPL-3.0 Section 13.
--- a/README.md
+++ b/README.md
@@ -213,9 +213,11 @@ Yes, for self-hosted. CloudCLI UI reads from and writes to the same `~/.claude`

 ## License

-GNU General Public License v3.0 - see [LICENSE](LICENSE) file for details.
+GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) — see [LICENSE](LICENSE) for the full text, including additional terms under Section 7.

-This project is open source and free to use, modify, and distribute under the GPL v3 license.
+This project is open source and free to use, modify, and distribute under the AGPL-3.0-or-later license. If you modify this software and run it as a network service, you must make your modified source code available to users of that service.
+
+CloudCLI UI  - (https://cloudcli.ai).

 ## Acknowledgments

--- a/package-lock.json
+++ b/package-lock.json
@@ -1,14 +1,14 @@
 {
  "name": "@siteboon/claude-code-ui",
-  "version": "1.25.2",
+  "version": "1.27.1",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@siteboon/claude-code-ui",
-      "version": "1.25.2",
+      "version": "1.27.1",
      "hasInstallScript": true,
-      "license": "GPL-3.0",
+      "license": "AGPL-3.0-or-later",
      "dependencies": {
        "@anthropic-ai/claude-agent-sdk": "^0.2.59",
        "@codemirror/lang-css": "^6.3.1",
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@siteboon/claude-code-ui",
-  "version": "1.25.2",
+  "version": "1.27.1",
  "description": "A web-based UI for Claude Code CLI",
  "type": "module",
  "main": "server/index.js",
@@ -46,7 +46,7 @@
    "mobile"
  ],
  "author": "CloudCLI UI Contributors",
-  "license": "GPL-3.0",
+  "license": "AGPL-3.0-or-later",
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.59",
    "@codemirror/lang-css": "^6.3.1",
--- a/public/sw.js
+++ b/public/sw.js
@@ -1,8 +1,8 @@
 // Service Worker for Claude Code UI PWA
-const CACHE_NAME = 'claude-ui-v1';
+// Cache only manifest (needed for PWA install). HTML and JS are never pre-cached
+// so a rebuild + refresh always picks up the latest assets.
+const CACHE_NAME = 'claude-ui-v2';
 const urlsToCache = [
-  '/',
-  '/index.html',
  '/manifest.json'
 ];

@@ -10,44 +10,63 @@ const urlsToCache = [
 self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(CACHE_NAME)
-      .then(cache => {
-        return cache.addAll(urlsToCache);
-      })
+      .then(cache => cache.addAll(urlsToCache))
  );
  self.skipWaiting();
 });

-// Fetch event
+// Fetch event — network-first for everything except hashed assets
 self.addEventListener('fetch', event => {
-  // Never cache API requests or WebSocket upgrades
-  if (event.request.url.includes('/api/') || event.request.url.includes('/ws')) {
+  const url = event.request.url;
+
+  // Never intercept API requests or WebSocket upgrades
+  if (url.includes('/api/') || url.includes('/ws')) {
    return;
  }

-  event.respondWith(
-    caches.match(event.request)
-      .then(response => {
-        if (response) {
+  // Navigation requests (HTML) — always go to network, no caching
+  if (event.request.mode === 'navigate') {
+    event.respondWith(
+      fetch(event.request).catch(() => caches.match('/manifest.json').then(() =>
+        new Response('<h1>Offline</h1><p>Please check your connection.</p>', {
+          headers: { 'Content-Type': 'text/html' }
+        })
+      ))
+    );
+    return;
+  }
+
+  // Hashed assets (JS/CSS in /assets/) — cache-first since filenames change per build
+  if (url.includes('/assets/')) {
+    event.respondWith(
+      caches.match(event.request).then(cached => {
+        if (cached) return cached;
+        return fetch(event.request).then(response => {
+          const clone = response.clone();
+          caches.open(CACHE_NAME).then(cache => cache.put(event.request, clone));
          return response;
-        }
-        return fetch(event.request);
-      }
-    )
+        });
+      })
+    );
+    return;
+  }
+
+  // Everything else — network-first
+  event.respondWith(
+    fetch(event.request).catch(() => caches.match(event.request))
  );
 });

-// Activate event
+// Activate event — purge old caches
 self.addEventListener('activate', event => {
  event.waitUntil(
-    caches.keys().then(cacheNames => {
-      return Promise.all(
-        cacheNames.map(cacheName => {
-          if (cacheName !== CACHE_NAME) {
-            return caches.delete(cacheName);
-          }
-        })
-      );
-    })
+    caches.keys().then(cacheNames =>
+      Promise.all(
+        cacheNames
+          .filter(name => name !== CACHE_NAME)
+          .map(name => caches.delete(name))
+      )
+    )
  );
  self.clients.claim();
 });
--- a/server/claude-sdk.js
+++ b/server/claude-sdk.js
@@ -24,6 +24,8 @@ import {
  notifyRunStopped,
  notifyUserIfEnabled
 } from './services/notification-orchestrator.js';
+import { claudeAdapter } from './providers/claude/adapter.js';
+import { createNormalizedMessage } from './providers/types.js';

 const activeSessions = new Map();
 const pendingToolApprovals = new Map();
@@ -142,7 +144,7 @@ function matchesToolPermission(entry, toolName, input) {
 * @returns {Object} SDK-compatible options
 */
 function mapCliOptionsToSDK(options = {}) {
-  const { sessionId, cwd, toolsSettings, permissionMode, images } = options;
+  const { sessionId, cwd, toolsSettings, permissionMode } = options;

  const sdkOptions = {};

@@ -193,7 +195,7 @@ function mapCliOptionsToSDK(options = {}) {
  // Map model (default to sonnet)
  // Valid models: sonnet, opus, haiku, opusplan, sonnet[1m]
  sdkOptions.model = options.model || CLAUDE_MODELS.DEFAULT;
-  console.log(`Using model: ${sdkOptions.model}`);
+  // Model logged at query start below

  // Map system prompt configuration
  sdkOptions.systemPrompt = {
@@ -304,7 +306,7 @@ function extractTokenBudget(resultMessage) {
  // This is the user's budget limit, not the model's context window
  const contextWindow = parseInt(process.env.CONTEXT_WINDOW) || 160000;

-  console.log(`Token calculation: input=${inputTokens}, output=${outputTokens}, cache=${cacheReadTokens + cacheCreationTokens}, total=${totalUsed}/${contextWindow}`);
+  // Token calc logged via token-budget WS event

  return {
    used: totalUsed,
@@ -360,7 +362,7 @@ async function handleImages(command, images, cwd) {
      modifiedCommand = command + imageNote;
    }

-    console.log(`Processed ${tempImagePaths.length} images to temp directory: ${tempDir}`);
+    // Images processed
    return { modifiedCommand, tempImagePaths, tempDir };
  } catch (error) {
    console.error('Error processing images for SDK:', error);
@@ -393,7 +395,7 @@ async function cleanupTempFiles(tempImagePaths, tempDir) {
      );
    }

-    console.log(`Cleaned up ${tempImagePaths.length} temp image files`);
+    // Temp files cleaned
  } catch (error) {
    console.error('Error during temp file cleanup:', error);
  }
@@ -413,7 +415,7 @@ async function loadMcpConfig(cwd) {
      await fs.access(claudeConfigPath);
    } catch (error) {
      // File doesn't exist, return null
-      console.log('No ~/.claude.json found, proceeding without MCP servers');
+      // No config file
      return null;
    }

@@ -433,7 +435,7 @@ async function loadMcpConfig(cwd) {
    // Add global MCP servers
    if (claudeConfig.mcpServers && typeof claudeConfig.mcpServers === 'object') {
      mcpServers = { ...claudeConfig.mcpServers };
-      console.log(`Loaded ${Object.keys(mcpServers).length} global MCP servers`);
+      // Global MCP servers loaded
    }

    // Add/override with project-specific MCP servers
@@ -441,17 +443,14 @@ async function loadMcpConfig(cwd) {
      const projectConfig = claudeConfig.claudeProjects[cwd];
      if (projectConfig && projectConfig.mcpServers && typeof projectConfig.mcpServers === 'object') {
        mcpServers = { ...mcpServers, ...projectConfig.mcpServers };
-        console.log(`Loaded ${Object.keys(projectConfig.mcpServers).length} project-specific MCP servers`);
+        // Project MCP servers merged
      }
    }

    // Return null if no servers found
    if (Object.keys(mcpServers).length === 0) {
-      console.log('No MCP servers configured');
      return null;
    }
-
-    console.log(`Total MCP servers loaded: ${Object.keys(mcpServers).length}`);
    return mcpServers;
  } catch (error) {
    console.error('Error loading MCP config:', error.message);
@@ -541,13 +540,7 @@ async function queryClaudeSDK(command, options = {}, ws) {
      }

      const requestId = createRequestId();
-      ws.send({
-        type: 'claude-permission-request',
-        requestId,
-        toolName,
-        input,
-        sessionId: capturedSessionId || sessionId || null
-      });
+      ws.send(createNormalizedMessage({ kind: 'permission_request', requestId, toolName, input, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
      emitNotification(createNotificationEvent({
        provider: 'claude',
        sessionId: capturedSessionId || sessionId || null,
@@ -569,12 +562,7 @@ async function queryClaudeSDK(command, options = {}, ws) {
          _receivedAt: new Date(),
        },
        onCancel: (reason) => {
-          ws.send({
-            type: 'claude-permission-cancelled',
-            requestId,
-            reason,
-            sessionId: capturedSessionId || sessionId || null
-          });
+          ws.send(createNormalizedMessage({ kind: 'permission_cancelled', requestId, reason, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
        }
      });
      if (!decision) {
@@ -650,39 +638,35 @@ async function queryClaudeSDK(command, options = {}, ws) {
        // Send session-created event only once for new sessions
        if (!sessionId && !sessionCreatedSent) {
          sessionCreatedSent = true;
-          ws.send({
-            type: 'session-created',
-            sessionId: capturedSessionId
-          });
-        } else {
-          console.log('Not sending session-created. sessionId:', sessionId, 'sessionCreatedSent:', sessionCreatedSent);
+          ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, sessionId: capturedSessionId, provider: 'claude' }));
        }
      } else {
-        console.log('No session_id in message or already captured. message.session_id:', message.session_id, 'capturedSessionId:', capturedSessionId);
+        // session_id already captured
      }

-      // Transform and send message to WebSocket
+      // Transform and normalize message via adapter
      const transformedMessage = transformMessage(message);
-      ws.send({
-        type: 'claude-response',
-        data: transformedMessage,
-        sessionId: capturedSessionId || sessionId || null
-      });
+      const sid = capturedSessionId || sessionId || null;
+
+      // Use adapter to normalize SDK events into NormalizedMessage[]
+      const normalized = claudeAdapter.normalizeMessage(transformedMessage, sid);
+      for (const msg of normalized) {
+        // Preserve parentToolUseId from SDK wrapper for subagent tool grouping
+        if (transformedMessage.parentToolUseId && !msg.parentToolUseId) {
+          msg.parentToolUseId = transformedMessage.parentToolUseId;
+        }
+        ws.send(msg);
+      }

      // Extract and send token budget updates from result messages
      if (message.type === 'result') {
        const models = Object.keys(message.modelUsage || {});
        if (models.length > 0) {
-          console.log("---> Model was sent using:", models);
+          // Model info available in result message
        }
-        const tokenBudget = extractTokenBudget(message);
-        if (tokenBudget) {
-          console.log('Token budget from modelUsage:', tokenBudget);
-          ws.send({
-            type: 'token-budget',
-            data: tokenBudget,
-            sessionId: capturedSessionId || sessionId || null
-          });
+        const tokenBudgetData = extractTokenBudget(message);
+        if (tokenBudgetData) {
+          ws.send(createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: tokenBudgetData, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
        }
      }
    }
@@ -696,13 +680,7 @@ async function queryClaudeSDK(command, options = {}, ws) {
    await cleanupTempFiles(tempImagePaths, tempDir);

    // Send completion event
-    console.log('Streaming complete, sending claude-complete event');
-    ws.send({
-      type: 'claude-complete',
-      sessionId: capturedSessionId,
-      exitCode: 0,
-      isNewSession: !sessionId && !!command
-    });
+    ws.send(createNormalizedMessage({ kind: 'complete', exitCode: 0, isNewSession: !sessionId && !!command, sessionId: capturedSessionId, provider: 'claude' }));
    notifyRunStopped({
      userId: ws?.userId || null,
      provider: 'claude',
@@ -710,7 +688,7 @@ async function queryClaudeSDK(command, options = {}, ws) {
      sessionName: sessionSummary,
      stopReason: 'completed'
    });
-    console.log('claude-complete event sent');
+    // Complete

  } catch (error) {
    console.error('SDK query error:', error);
@@ -724,11 +702,7 @@ async function queryClaudeSDK(command, options = {}, ws) {
    await cleanupTempFiles(tempImagePaths, tempDir);

    // Send error to WebSocket
-    ws.send({
-      type: 'claude-error',
-      error: error.message,
-      sessionId: capturedSessionId || sessionId || null
-    });
+    ws.send(createNormalizedMessage({ kind: 'error', content: error.message, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
    notifyRunFailed({
      userId: ws?.userId || null,
      provider: 'claude',
--- a/server/cursor-cli.js
+++ b/server/cursor-cli.js
@@ -1,6 +1,8 @@
 import { spawn } from 'child_process';
 import crossSpawn from 'cross-spawn';
 import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
+import { cursorAdapter } from './providers/cursor/adapter.js';
+import { createNormalizedMessage } from './providers/types.js';

 // Use cross-spawn on Windows for better command execution
 const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
@@ -172,75 +174,42 @@ async function spawnCursor(command, options = {}, ws) {
                  // Send session-created event only once for new sessions
                  if (!sessionId && !sessionCreatedSent) {
                    sessionCreatedSent = true;
-                    ws.send({
-                      type: 'session-created',
-                      sessionId: capturedSessionId,
-                      model: response.model,
-                      cwd: response.cwd
-                    });
+                    ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, model: response.model, cwd: response.cwd, sessionId: capturedSessionId, provider: 'cursor' }));
                  }
                }

-                // Send system info to frontend
-                ws.send({
-                  type: 'cursor-system',
-                  data: response,
-                  sessionId: capturedSessionId || sessionId || null
-                });
+                // System info — no longer needed by the frontend (session-lifecycle 'created' handles nav).
              }
              break;

            case 'user':
-              // Forward user message
-              ws.send({
-                type: 'cursor-user',
-                data: response,
-                sessionId: capturedSessionId || sessionId || null
-              });
+              // User messages are not displayed in the UI — skip.
              break;

            case 'assistant':
              // Accumulate assistant message chunks
              if (response.message && response.message.content && response.message.content.length > 0) {
-                const textContent = response.message.content[0].text;
-
-                // Send as Claude-compatible format for frontend
-                ws.send({
-                  type: 'claude-response',
-                  data: {
-                    type: 'content_block_delta',
-                    delta: {
-                      type: 'text_delta',
-                      text: textContent
-                    }
-                  },
-                  sessionId: capturedSessionId || sessionId || null
-                });
+                const normalized = cursorAdapter.normalizeMessage(response, capturedSessionId || sessionId || null);
+                for (const msg of normalized) ws.send(msg);
              }
              break;

-            case 'result':
-              // Session complete
+            case 'result': {
+              // Session complete — send stream end + lifecycle complete with result payload
              console.log('Cursor session result:', response);
-
-              // Do not emit an extra content_block_stop here.
-              // The UI already finalizes the streaming message in cursor-result handling,
-              // and emitting both can produce duplicate assistant messages.
-              ws.send({
-                type: 'cursor-result',
-                sessionId: capturedSessionId || sessionId,
-                data: response,
-                success: response.subtype === 'success'
-              });
+              const resultText = typeof response.result === 'string' ? response.result : '';
+              ws.send(createNormalizedMessage({
+                kind: 'complete',
+                exitCode: response.subtype === 'success' ? 0 : 1,
+                resultText,
+                isError: response.subtype !== 'success',
+                sessionId: capturedSessionId || sessionId, provider: 'cursor',
+              }));
              break;
+            }

            default:
-              // Forward any other message types
-              ws.send({
-                type: 'cursor-response',
-                data: response,
-                sessionId: capturedSessionId || sessionId || null
-              });
+              // Unknown message types — ignore.
          }
        } catch (parseError) {
          console.log('Non-JSON response:', line);
@@ -249,12 +218,9 @@ async function spawnCursor(command, options = {}, ws) {
            return;
          }

-          // If not JSON, send as raw text
-          ws.send({
-            type: 'cursor-output',
-            data: line,
-            sessionId: capturedSessionId || sessionId || null
-          });
+          // If not JSON, send as stream delta via adapter
+          const normalized = cursorAdapter.normalizeMessage(line, capturedSessionId || sessionId || null);
+          for (const msg of normalized) ws.send(msg);
        }
      };

@@ -282,12 +248,7 @@ async function spawnCursor(command, options = {}, ws) {
          return;
        }

-        ws.send({
-          type: 'cursor-error',
-          error: stderrText,
-          sessionId: capturedSessionId || sessionId || null,
-          provider: 'cursor'
-        });
+        ws.send(createNormalizedMessage({ kind: 'error', content: stderrText, sessionId: capturedSessionId || sessionId || null, provider: 'cursor' }));
      });

      // Handle process completion
@@ -314,13 +275,7 @@ async function spawnCursor(command, options = {}, ws) {
          return;
        }

-        ws.send({
-          type: 'claude-complete',
-          sessionId: finalSessionId,
-          exitCode: code,
-          provider: 'cursor',
-          isNewSession: !sessionId && !!command // Flag to indicate this was a new session
-        });
+        ws.send(createNormalizedMessage({ kind: 'complete', exitCode: code, isNewSession: !sessionId && !!command, sessionId: finalSessionId, provider: 'cursor' }));

        if (code === 0) {
          notifyTerminalState({ code });
@@ -339,12 +294,7 @@ async function spawnCursor(command, options = {}, ws) {
        const finalSessionId = capturedSessionId || sessionId || processKey;
        activeCursorProcesses.delete(finalSessionId);

-        ws.send({
-          type: 'cursor-error',
-          error: error.message,
-          sessionId: capturedSessionId || sessionId || null,
-          provider: 'cursor'
-        });
+        ws.send(createNormalizedMessage({ kind: 'error', content: error.message, sessionId: capturedSessionId || sessionId || null, provider: 'cursor' }));
        notifyTerminalState({ error });

        settleOnce(() => reject(error));
--- a/server/gemini-cli.js
+++ b/server/gemini-cli.js
@@ -6,15 +6,15 @@ const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
-import { getSessions, getSessionMessages } from './projects.js';
 import sessionManager from './sessionManager.js';
 import GeminiResponseHandler from './gemini-response-handler.js';
 import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
+import { createNormalizedMessage } from './providers/types.js';

 let activeGeminiProcesses = new Map(); // Track active processes by session ID

 async function spawnGemini(command, options = {}, ws) {
-    const { sessionId, projectPath, cwd, resume, toolsSettings, permissionMode, images, sessionSummary } = options;
+    const { sessionId, projectPath, cwd, toolsSettings, permissionMode, images, sessionSummary } = options;
    let capturedSessionId = sessionId; // Track session ID throughout the process
    let sessionCreatedSent = false; // Track if we've already sent session-created event
    let assistantBlocks = []; // Accumulate the full response blocks including tools
@@ -219,7 +219,6 @@ async function spawnGemini(command, options = {}, ws) {
        geminiProcess.stdin.end();

        // Add timeout handler
-        let hasReceivedOutput = false;
        const timeoutMs = 120000; // 120 seconds for slower models
        let timeout;

@@ -228,12 +227,7 @@ async function spawnGemini(command, options = {}, ws) {
            timeout = setTimeout(() => {
                const socketSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : (capturedSessionId || sessionId || processKey);
                terminalFailureReason = `Gemini CLI timeout - no response received for ${timeoutMs / 1000} seconds`;
-                ws.send({
-                    type: 'gemini-error',
-                    sessionId: socketSessionId,
-                    error: terminalFailureReason,
-                    provider: 'gemini'
-                });
+                ws.send(createNormalizedMessage({ kind: 'error', content: terminalFailureReason, sessionId: socketSessionId, provider: 'gemini' }));
                try {
                    geminiProcess.kill('SIGTERM');
                } catch (e) { }
@@ -295,7 +289,6 @@ async function spawnGemini(command, options = {}, ws) {
        // Handle stdout
        geminiProcess.stdout.on('data', (data) => {
            const rawOutput = data.toString();
-            hasReceivedOutput = true;
            startTimeout(); // Re-arm the timeout

            // For new sessions, create a session ID FIRST
@@ -319,21 +312,7 @@ async function spawnGemini(command, options = {}, ws) {

                ws.setSessionId && typeof ws.setSessionId === 'function' && ws.setSessionId(capturedSessionId);

-                ws.send({
-                    type: 'session-created',
-                    sessionId: capturedSessionId
-                });
-
-                // Emit fake system init so the frontend immediately navigates and saves the session
-                ws.send({
-                    type: 'claude-response',
-                    sessionId: capturedSessionId,
-                    data: {
-                        type: 'system',
-                        subtype: 'init',
-                        session_id: capturedSessionId
-                    }
-                });
+                ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, sessionId: capturedSessionId, provider: 'gemini' }));
            }

            if (responseHandler) {
@@ -346,14 +325,7 @@ async function spawnGemini(command, options = {}, ws) {
                    assistantBlocks.push({ type: 'text', text: rawOutput });
                }
                const socketSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : (capturedSessionId || sessionId);
-                ws.send({
-                    type: 'gemini-response',
-                    sessionId: socketSessionId,
-                    data: {
-                        type: 'message',
-                        content: rawOutput
-                    }
-                });
+                ws.send(createNormalizedMessage({ kind: 'stream_delta', content: rawOutput, sessionId: socketSessionId, provider: 'gemini' }));
            }
        });

@@ -370,12 +342,7 @@ async function spawnGemini(command, options = {}, ws) {
            }

            const socketSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : (capturedSessionId || sessionId);
-            ws.send({
-                type: 'gemini-error',
-                sessionId: socketSessionId,
-                error: errorMsg,
-                provider: 'gemini'
-            });
+            ws.send(createNormalizedMessage({ kind: 'error', content: errorMsg, sessionId: socketSessionId, provider: 'gemini' }));
        });

        // Handle process completion
@@ -397,13 +364,7 @@ async function spawnGemini(command, options = {}, ws) {
                sessionManager.addMessage(finalSessionId, 'assistant', assistantBlocks);
            }

-            ws.send({
-                type: 'claude-complete', // Use claude-complete for compatibility with UI
-                sessionId: finalSessionId,
-                exitCode: code,
-                provider: 'gemini',
-                isNewSession: !sessionId && !!command // Flag to indicate this was a new session
-            });
+            ws.send(createNormalizedMessage({ kind: 'complete', exitCode: code, isNewSession: !sessionId && !!command, sessionId: finalSessionId, provider: 'gemini' }));

            // Clean up temporary image files if any
            if (geminiProcess.tempImagePaths && geminiProcess.tempImagePaths.length > 0) {
@@ -434,12 +395,7 @@ async function spawnGemini(command, options = {}, ws) {
            activeGeminiProcesses.delete(finalSessionId);

            const errorSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : finalSessionId;
-            ws.send({
-                type: 'gemini-error',
-                sessionId: errorSessionId,
-                error: error.message,
-                provider: 'gemini'
-            });
+            ws.send(createNormalizedMessage({ kind: 'error', content: error.message, sessionId: errorSessionId, provider: 'gemini' }));
            notifyTerminalState({ error });

            reject(error);
--- a/server/gemini-response-handler.js
+++ b/server/gemini-response-handler.js
@@ -1,4 +1,6 @@
 // Gemini Response Handler - JSON Stream processing
+import { geminiAdapter } from './providers/gemini/adapter.js';
+
 class GeminiResponseHandler {
  constructor(ws, options = {}) {
    this.ws = ws;
@@ -27,13 +29,12 @@ class GeminiResponseHandler {
        this.handleEvent(event);
      } catch (err) {
        // Not a JSON line, probably debug output or CLI warnings
-        // console.error('[Gemini Handler] Non-JSON line ignored:', line);
      }
    }
  }

  handleEvent(event) {
-    const socketSessionId = typeof this.ws.getSessionId === 'function' ? this.ws.getSessionId() : null;
+    const sid = typeof this.ws.getSessionId === 'function' ? this.ws.getSessionId() : null;

    if (event.type === 'init') {
      if (this.onInit) {
@@ -42,88 +43,26 @@ class GeminiResponseHandler {
      return;
    }

+    // Invoke per-type callbacks for session tracking
    if (event.type === 'message' && event.role === 'assistant') {
      const content = event.content || '';
-
-      // Notify the parent CLI handler of accumulated text
      if (this.onContentFragment && content) {
        this.onContentFragment(content);
      }
+    } else if (event.type === 'tool_use' && this.onToolUse) {
+      this.onToolUse(event);
+    } else if (event.type === 'tool_result' && this.onToolResult) {
+      this.onToolResult(event);
+    }

-      let payload = {
-        type: 'gemini-response',
-        data: {
-          type: 'message',
-          content: content,
-          isPartial: event.delta === true
-        }
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
-    }
-    else if (event.type === 'tool_use') {
-      if (this.onToolUse) {
-        this.onToolUse(event);
-      }
-      let payload = {
-        type: 'gemini-tool-use',
-        toolName: event.tool_name,
-        toolId: event.tool_id,
-        parameters: event.parameters || {}
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
-    }
-    else if (event.type === 'tool_result') {
-      if (this.onToolResult) {
-        this.onToolResult(event);
-      }
-      let payload = {
-        type: 'gemini-tool-result',
-        toolId: event.tool_id,
-        status: event.status,
-        output: event.output || ''
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
-    }
-    else if (event.type === 'result') {
-      // Send a finalize message string
-      let payload = {
-        type: 'gemini-response',
-        data: {
-          type: 'message',
-          content: '',
-          isPartial: false
-        }
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
-
-      if (event.stats && event.stats.total_tokens) {
-        let statsPayload = {
-          type: 'claude-status',
-          data: {
-            status: 'Complete',
-            tokens: event.stats.total_tokens
-          }
-        };
-        if (socketSessionId) statsPayload.sessionId = socketSessionId;
-        this.ws.send(statsPayload);
-      }
-    }
-    else if (event.type === 'error') {
-      let payload = {
-        type: 'gemini-error',
-        error: event.error || event.message || 'Unknown Gemini streaming error'
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
+    // Normalize via adapter and send all resulting messages
+    const normalized = geminiAdapter.normalizeMessage(event, sid);
+    for (const msg of normalized) {
+      this.ws.send(msg);
    }
  }

  forceFlush() {
-    // If the buffer has content, try to parse it one last time
    if (this.buffer.trim()) {
      try {
        const event = JSON.parse(this.buffer);
--- a/server/index.js
+++ b/server/index.js
@@ -44,7 +44,7 @@ import pty from 'node-pty';
 import fetch from 'node-fetch';
 import mime from 'mime-types';

-import { getProjects, getSessions, getSessionMessages, renameProject, deleteSession, deleteProject, addProjectManually, extractProjectDirectory, clearProjectDirectoryCache, searchConversations } from './projects.js';
+import { getProjects, getSessions, renameProject, deleteSession, deleteProject, addProjectManually, extractProjectDirectory, clearProjectDirectoryCache, searchConversations } from './projects.js';
 import { queryClaudeSDK, abortClaudeSDKSession, isClaudeSDKSessionActive, getActiveClaudeSDKSessions, resolveToolApproval, getPendingApprovalsForSession, reconnectSessionWriter } from './claude-sdk.js';
 import { spawnCursor, abortCursorSession, isCursorSessionActive, getActiveCursorSessions } from './cursor-cli.js';
 import { queryCodex, abortCodexSession, isCodexSessionActive, getActiveCodexSessions } from './openai-codex.js';
@@ -65,6 +65,8 @@ import userRoutes from './routes/user.js';
 import codexRoutes from './routes/codex.js';
 import geminiRoutes from './routes/gemini.js';
 import pluginsRoutes from './routes/plugins.js';
+import messagesRoutes from './routes/messages.js';
+import { createNormalizedMessage } from './providers/types.js';
 import { startEnabledPluginServers, stopAllPlugins, getPluginPort } from './utils/plugin-process-manager.js';
 import { initializeDatabase, sessionNamesDb, applyCustomSessionNames } from './database/db.js';
 import { configureWebPush } from './services/vapid-keys.js';
@@ -396,6 +398,9 @@ app.use('/api/gemini', authenticateToken, geminiRoutes);
 // Plugins API Routes (protected)
 app.use('/api/plugins', authenticateToken, pluginsRoutes);

+// Unified session messages route (protected)
+app.use('/api/sessions', authenticateToken, messagesRoutes);
+
 // Agent API Routes (uses API key authentication)
 app.use('/api/agent', agentRoutes);

@@ -509,31 +514,6 @@ app.get('/api/projects/:projectName/sessions', authenticateToken, async (req, re
    }
 });

-// Get messages for a specific session
-app.get('/api/projects/:projectName/sessions/:sessionId/messages', authenticateToken, async (req, res) => {
-    try {
-        const { projectName, sessionId } = req.params;
-        const { limit, offset } = req.query;
-
-        // Parse limit and offset if provided
-        const parsedLimit = limit ? parseInt(limit, 10) : null;
-        const parsedOffset = offset ? parseInt(offset, 10) : 0;
-
-        const result = await getSessionMessages(projectName, sessionId, parsedLimit, parsedOffset);
-
-        // Handle both old and new response formats
-        if (Array.isArray(result)) {
-            // Backward compatibility: no pagination parameters were provided
-            res.json({ messages: result });
-        } else {
-            // New format with pagination info
-            res.json(result);
-        }
-    } catch (error) {
-        res.status(500).json({ error: error.message });
-    }
-});
-
 // Rename project endpoint
 app.put('/api/projects/:projectName/rename', authenticateToken, async (req, res) => {
    try {
@@ -958,7 +938,6 @@ app.get('/api/projects/:projectName/files', authenticateToken, async (req, res)
        }

        const files = await getFileTree(actualPath, 10, 0, true);
-        const hiddenFiles = files.filter(f => f.name.startsWith('.'));
        res.json(files);
    } catch (error) {
        console.error('[ERROR] File tree error:', error.message);
@@ -1463,6 +1442,10 @@ wss.on('connection', (ws, request) => {

 /**
 * WebSocket Writer - Wrapper for WebSocket to match SSEStreamWriter interface
+ *
+ * Provider files use `createNormalizedMessage()` from `providers/types.js` and
+ * adapter `normalizeMessage()` to produce unified NormalizedMessage events.
+ * The writer simply serialises and sends.
 */
 class WebSocketWriter {
    constructor(ws, userId = null) {
@@ -1474,7 +1457,6 @@ class WebSocketWriter {

    send(data) {
        if (this.ws.readyState === 1) { // WebSocket.OPEN
-            // Providers send raw objects, we stringify for WebSocket
            this.ws.send(JSON.stringify(data));
        }
    }
@@ -1555,12 +1537,7 @@ function handleChatConnection(ws, request) {
                    success = await abortClaudeSDKSession(data.sessionId);
                }

-                writer.send({
-                    type: 'session-aborted',
-                    sessionId: data.sessionId,
-                    provider,
-                    success
-                });
+                writer.send(createNormalizedMessage({ kind: 'complete', exitCode: success ? 0 : 1, aborted: true, success, sessionId: data.sessionId, provider }));
            } else if (data.type === 'claude-permission-response') {
                // Relay UI approval decisions back into the SDK control flow.
                // This does not persist permissions; it only resolves the in-flight request,
@@ -1576,12 +1553,7 @@ function handleChatConnection(ws, request) {
            } else if (data.type === 'cursor-abort') {
                console.log('[DEBUG] Abort Cursor session:', data.sessionId);
                const success = abortCursorSession(data.sessionId);
-                writer.send({
-                    type: 'session-aborted',
-                    sessionId: data.sessionId,
-                    provider: 'cursor',
-                    success
-                });
+                writer.send(createNormalizedMessage({ kind: 'complete', exitCode: success ? 0 : 1, aborted: true, success, sessionId: data.sessionId, provider: 'cursor' }));
            } else if (data.type === 'check-session-status') {
                // Check if a specific session is currently processing
                const provider = data.provider || 'claude';
--- a/server/openai-codex.js
+++ b/server/openai-codex.js
@@ -15,6 +15,8 @@

 import { Codex } from '@openai/codex-sdk';
 import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
+import { codexAdapter } from './providers/codex/adapter.js';
+import { createNormalizedMessage } from './providers/types.js';

 // Track active sessions
 const activeCodexSessions = new Map();
@@ -241,11 +243,7 @@ export async function queryCodex(command, options = {}, ws) {
    });

    // Send session created event
-    sendMessage(ws, {
-      type: 'session-created',
-      sessionId: currentSessionId,
-      provider: 'codex'
-    });
+    sendMessage(ws, createNormalizedMessage({ kind: 'session_created', newSessionId: currentSessionId, sessionId: currentSessionId, provider: 'codex' }));

    // Execute with streaming
    const streamedTurn = await thread.runStreamed(command, {
@@ -265,11 +263,11 @@ export async function queryCodex(command, options = {}, ws) {

      const transformed = transformCodexEvent(event);

-      sendMessage(ws, {
-        type: 'codex-response',
-        data: transformed,
-        sessionId: currentSessionId
-      });
+      // Normalize the transformed event into NormalizedMessage(s) via adapter
+      const normalizedMsgs = codexAdapter.normalizeMessage(transformed, currentSessionId);
+      for (const msg of normalizedMsgs) {
+        sendMessage(ws, msg);
+      }

      if (event.type === 'turn.failed' && !terminalFailure) {
        terminalFailure = event.error || new Error('Turn failed');
@@ -285,25 +283,13 @@ export async function queryCodex(command, options = {}, ws) {
      // Extract and send token usage if available (normalized to match Claude format)
      if (event.type === 'turn.completed' && event.usage) {
        const totalTokens = (event.usage.input_tokens || 0) + (event.usage.output_tokens || 0);
-        sendMessage(ws, {
-          type: 'token-budget',
-          data: {
-            used: totalTokens,
-            total: 200000 // Default context window for Codex models
-          },
-          sessionId: currentSessionId
-        });
+        sendMessage(ws, createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: { used: totalTokens, total: 200000 }, sessionId: currentSessionId, provider: 'codex' }));
      }
    }

    // Send completion event
    if (!terminalFailure) {
-      sendMessage(ws, {
-        type: 'codex-complete',
-        sessionId: currentSessionId,
-        actualSessionId: thread.id,
-        provider: 'codex'
-      });
+      sendMessage(ws, createNormalizedMessage({ kind: 'complete', actualSessionId: thread.id, sessionId: currentSessionId, provider: 'codex' }));
      notifyRunStopped({
        userId: ws?.userId || null,
        provider: 'codex',
@@ -322,12 +308,7 @@ export async function queryCodex(command, options = {}, ws) {

    if (!wasAborted) {
      console.error('[Codex] Error:', error);
-      sendMessage(ws, {
-        type: 'codex-error',
-        error: error.message,
-        sessionId: currentSessionId,
-        provider: 'codex'
-      });
+      sendMessage(ws, createNormalizedMessage({ kind: 'error', content: error.message, sessionId: currentSessionId, provider: 'codex' }));
      if (!terminalFailure) {
        notifyRunFailed({
          userId: ws?.userId || null,
--- a/server/projects.js
+++ b/server/projects.js
@@ -1014,7 +1014,7 @@ async function getSessionMessages(projectName, sessionId, limit = null, offset =
              messages.push(entry);
            }
          } catch (parseError) {
-            console.warn('Error parsing line:', parseError.message);
+            // Silently skip malformed JSONL lines (common with concurrent writes)
          }
        }
      }
--- a/server/providers/claude/adapter.js
+++ b/server/providers/claude/adapter.js
@@ -0,0 +1,278 @@
+/**
+ * Claude provider adapter.
+ *
+ * Normalizes Claude SDK session history into NormalizedMessage format.
+ * @module adapters/claude
+ */
+
+import { getSessionMessages } from '../../projects.js';
+import { createNormalizedMessage, generateMessageId } from '../types.js';
+import { isInternalContent } from '../utils.js';
+
+const PROVIDER = 'claude';
+
+/**
+ * Normalize a raw JSONL message or realtime SDK event into NormalizedMessage(s).
+ * Handles both history entries (JSONL `{ message: { role, content } }`) and
+ * realtime streaming events (`content_block_delta`, `content_block_stop`, etc.).
+ * @param {object} raw - A single entry from JSONL or a live SDK event
+ * @param {string} sessionId
+ * @returns {import('../types.js').NormalizedMessage[]}
+ */
+export function normalizeMessage(raw, sessionId) {
+  // ── Streaming events (realtime) ──────────────────────────────────────────
+  if (raw.type === 'content_block_delta' && raw.delta?.text) {
+    return [createNormalizedMessage({ kind: 'stream_delta', content: raw.delta.text, sessionId, provider: PROVIDER })];
+  }
+  if (raw.type === 'content_block_stop') {
+    return [createNormalizedMessage({ kind: 'stream_end', sessionId, provider: PROVIDER })];
+  }
+
+  // ── History / full-message events ────────────────────────────────────────
+  const messages = [];
+  const ts = raw.timestamp || new Date().toISOString();
+  const baseId = raw.uuid || generateMessageId('claude');
+
+  // User message
+  if (raw.message?.role === 'user' && raw.message?.content) {
+    if (Array.isArray(raw.message.content)) {
+      // Handle tool_result parts
+      for (const part of raw.message.content) {
+        if (part.type === 'tool_result') {
+          messages.push(createNormalizedMessage({
+            id: `${baseId}_tr_${part.tool_use_id}`,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_result',
+            toolId: part.tool_use_id,
+            content: typeof part.content === 'string' ? part.content : JSON.stringify(part.content),
+            isError: Boolean(part.is_error),
+            subagentTools: raw.subagentTools,
+            toolUseResult: raw.toolUseResult,
+          }));
+        } else if (part.type === 'text') {
+          // Regular text parts from user
+          const text = part.text || '';
+          if (text && !isInternalContent(text)) {
+            messages.push(createNormalizedMessage({
+              id: `${baseId}_text`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'text',
+              role: 'user',
+              content: text,
+            }));
+          }
+        }
+      }
+
+      // If no text parts were found, check if it's a pure user message
+      if (messages.length === 0) {
+        const textParts = raw.message.content
+          .filter(p => p.type === 'text')
+          .map(p => p.text)
+          .filter(Boolean)
+          .join('\n');
+        if (textParts && !isInternalContent(textParts)) {
+          messages.push(createNormalizedMessage({
+            id: `${baseId}_text`,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'text',
+            role: 'user',
+            content: textParts,
+          }));
+        }
+      }
+    } else if (typeof raw.message.content === 'string') {
+      const text = raw.message.content;
+      if (text && !isInternalContent(text)) {
+        messages.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp: ts,
+          provider: PROVIDER,
+          kind: 'text',
+          role: 'user',
+          content: text,
+        }));
+      }
+    }
+    return messages;
+  }
+
+  // Thinking message
+  if (raw.type === 'thinking' && raw.message?.content) {
+    messages.push(createNormalizedMessage({
+      id: baseId,
+      sessionId,
+      timestamp: ts,
+      provider: PROVIDER,
+      kind: 'thinking',
+      content: raw.message.content,
+    }));
+    return messages;
+  }
+
+  // Tool use result (codex-style in Claude)
+  if (raw.type === 'tool_use' && raw.toolName) {
+    messages.push(createNormalizedMessage({
+      id: baseId,
+      sessionId,
+      timestamp: ts,
+      provider: PROVIDER,
+      kind: 'tool_use',
+      toolName: raw.toolName,
+      toolInput: raw.toolInput,
+      toolId: raw.toolCallId || baseId,
+    }));
+    return messages;
+  }
+
+  if (raw.type === 'tool_result') {
+    messages.push(createNormalizedMessage({
+      id: baseId,
+      sessionId,
+      timestamp: ts,
+      provider: PROVIDER,
+      kind: 'tool_result',
+      toolId: raw.toolCallId || '',
+      content: raw.output || '',
+      isError: false,
+    }));
+    return messages;
+  }
+
+  // Assistant message
+  if (raw.message?.role === 'assistant' && raw.message?.content) {
+    if (Array.isArray(raw.message.content)) {
+      let partIndex = 0;
+      for (const part of raw.message.content) {
+        if (part.type === 'text' && part.text) {
+          messages.push(createNormalizedMessage({
+            id: `${baseId}_${partIndex}`,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'text',
+            role: 'assistant',
+            content: part.text,
+          }));
+        } else if (part.type === 'tool_use') {
+          messages.push(createNormalizedMessage({
+            id: `${baseId}_${partIndex}`,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: part.name,
+            toolInput: part.input,
+            toolId: part.id,
+          }));
+        } else if (part.type === 'thinking' && part.thinking) {
+          messages.push(createNormalizedMessage({
+            id: `${baseId}_${partIndex}`,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'thinking',
+            content: part.thinking,
+          }));
+        }
+        partIndex++;
+      }
+    } else if (typeof raw.message.content === 'string') {
+      messages.push(createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'text',
+        role: 'assistant',
+        content: raw.message.content,
+      }));
+    }
+    return messages;
+  }
+
+  return messages;
+}
+
+/**
+ * @type {import('../types.js').ProviderAdapter}
+ */
+export const claudeAdapter = {
+  normalizeMessage,
+
+  /**
+   * Fetch session history from JSONL files, returning normalized messages.
+   */
+  async fetchHistory(sessionId, opts = {}) {
+    const { projectName, limit = null, offset = 0 } = opts;
+    if (!projectName) {
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    let result;
+    try {
+      result = await getSessionMessages(projectName, sessionId, limit, offset);
+    } catch (error) {
+      console.warn(`[ClaudeAdapter] Failed to load session ${sessionId}:`, error.message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    // getSessionMessages returns either an array (no limit) or { messages, total, hasMore }
+    const rawMessages = Array.isArray(result) ? result : (result.messages || []);
+    const total = Array.isArray(result) ? rawMessages.length : (result.total || 0);
+    const hasMore = Array.isArray(result) ? false : Boolean(result.hasMore);
+
+    // First pass: collect tool results for attachment to tool_use messages
+    const toolResultMap = new Map();
+    for (const raw of rawMessages) {
+      if (raw.message?.role === 'user' && Array.isArray(raw.message?.content)) {
+        for (const part of raw.message.content) {
+          if (part.type === 'tool_result') {
+            toolResultMap.set(part.tool_use_id, {
+              content: part.content,
+              isError: Boolean(part.is_error),
+              timestamp: raw.timestamp,
+              subagentTools: raw.subagentTools,
+              toolUseResult: raw.toolUseResult,
+            });
+          }
+        }
+      }
+    }
+
+    // Second pass: normalize all messages
+    const normalized = [];
+    for (const raw of rawMessages) {
+      const entries = normalizeMessage(raw, sessionId);
+      normalized.push(...entries);
+    }
+
+    // Attach tool results to their corresponding tool_use messages
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_use' && msg.toolId && toolResultMap.has(msg.toolId)) {
+        const tr = toolResultMap.get(msg.toolId);
+        msg.toolResult = {
+          content: typeof tr.content === 'string' ? tr.content : JSON.stringify(tr.content),
+          isError: tr.isError,
+          toolUseResult: tr.toolUseResult,
+        };
+        msg.subagentTools = tr.subagentTools;
+      }
+    }
+
+    return {
+      messages: normalized,
+      total,
+      hasMore,
+      offset,
+      limit,
+    };
+  },
+};
--- a/server/providers/codex/adapter.js
+++ b/server/providers/codex/adapter.js
@@ -0,0 +1,248 @@
+/**
+ * Codex (OpenAI) provider adapter.
+ *
+ * Normalizes Codex SDK session history into NormalizedMessage format.
+ * @module adapters/codex
+ */
+
+import { getCodexSessionMessages } from '../../projects.js';
+import { createNormalizedMessage, generateMessageId } from '../types.js';
+
+const PROVIDER = 'codex';
+
+/**
+ * Normalize a raw Codex JSONL message into NormalizedMessage(s).
+ * @param {object} raw - A single parsed message from Codex JSONL
+ * @param {string} sessionId
+ * @returns {import('../types.js').NormalizedMessage[]}
+ */
+function normalizeCodexHistoryEntry(raw, sessionId) {
+  const ts = raw.timestamp || new Date().toISOString();
+  const baseId = raw.uuid || generateMessageId('codex');
+
+  // User message
+  if (raw.message?.role === 'user') {
+    const content = typeof raw.message.content === 'string'
+      ? raw.message.content
+      : Array.isArray(raw.message.content)
+        ? raw.message.content.map(p => typeof p === 'string' ? p : p?.text || '').filter(Boolean).join('\n')
+        : String(raw.message.content || '');
+    if (!content.trim()) return [];
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId,
+      timestamp: ts,
+      provider: PROVIDER,
+      kind: 'text',
+      role: 'user',
+      content,
+    })];
+  }
+
+  // Assistant message
+  if (raw.message?.role === 'assistant') {
+    const content = typeof raw.message.content === 'string'
+      ? raw.message.content
+      : Array.isArray(raw.message.content)
+        ? raw.message.content.map(p => typeof p === 'string' ? p : p?.text || '').filter(Boolean).join('\n')
+        : '';
+    if (!content.trim()) return [];
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId,
+      timestamp: ts,
+      provider: PROVIDER,
+      kind: 'text',
+      role: 'assistant',
+      content,
+    })];
+  }
+
+  // Thinking/reasoning
+  if (raw.type === 'thinking' || raw.isReasoning) {
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId,
+      timestamp: ts,
+      provider: PROVIDER,
+      kind: 'thinking',
+      content: raw.message?.content || '',
+    })];
+  }
+
+  // Tool use
+  if (raw.type === 'tool_use' || raw.toolName) {
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId,
+      timestamp: ts,
+      provider: PROVIDER,
+      kind: 'tool_use',
+      toolName: raw.toolName || 'Unknown',
+      toolInput: raw.toolInput,
+      toolId: raw.toolCallId || baseId,
+    })];
+  }
+
+  // Tool result
+  if (raw.type === 'tool_result') {
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId,
+      timestamp: ts,
+      provider: PROVIDER,
+      kind: 'tool_result',
+      toolId: raw.toolCallId || '',
+      content: raw.output || '',
+      isError: Boolean(raw.isError),
+    })];
+  }
+
+  return [];
+}
+
+/**
+ * Normalize a raw Codex event (history JSONL or transformed SDK event) into NormalizedMessage(s).
+ * @param {object} raw - A history entry (has raw.message.role) or transformed SDK event (has raw.type)
+ * @param {string} sessionId
+ * @returns {import('../types.js').NormalizedMessage[]}
+ */
+export function normalizeMessage(raw, sessionId) {
+  // History format: has message.role
+  if (raw.message?.role) {
+    return normalizeCodexHistoryEntry(raw, sessionId);
+  }
+
+  const ts = raw.timestamp || new Date().toISOString();
+  const baseId = raw.uuid || generateMessageId('codex');
+
+  // SDK event format (output of transformCodexEvent)
+  if (raw.type === 'item') {
+    switch (raw.itemType) {
+      case 'agent_message':
+        return [createNormalizedMessage({
+          id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+          kind: 'text', role: 'assistant', content: raw.message?.content || '',
+        })];
+      case 'reasoning':
+        return [createNormalizedMessage({
+          id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+          kind: 'thinking', content: raw.message?.content || '',
+        })];
+      case 'command_execution':
+        return [createNormalizedMessage({
+          id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+          kind: 'tool_use', toolName: 'Bash', toolInput: { command: raw.command },
+          toolId: baseId,
+          output: raw.output, exitCode: raw.exitCode, status: raw.status,
+        })];
+      case 'file_change':
+        return [createNormalizedMessage({
+          id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+          kind: 'tool_use', toolName: 'FileChanges', toolInput: raw.changes,
+          toolId: baseId, status: raw.status,
+        })];
+      case 'mcp_tool_call':
+        return [createNormalizedMessage({
+          id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+          kind: 'tool_use', toolName: raw.tool || 'MCP', toolInput: raw.arguments,
+          toolId: baseId, server: raw.server, result: raw.result,
+          error: raw.error, status: raw.status,
+        })];
+      case 'web_search':
+        return [createNormalizedMessage({
+          id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+          kind: 'tool_use', toolName: 'WebSearch', toolInput: { query: raw.query },
+          toolId: baseId,
+        })];
+      case 'todo_list':
+        return [createNormalizedMessage({
+          id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+          kind: 'tool_use', toolName: 'TodoList', toolInput: { items: raw.items },
+          toolId: baseId,
+        })];
+      case 'error':
+        return [createNormalizedMessage({
+          id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+          kind: 'error', content: raw.message?.content || 'Unknown error',
+        })];
+      default:
+        // Unknown item type — pass through as generic tool_use
+        return [createNormalizedMessage({
+          id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+          kind: 'tool_use', toolName: raw.itemType || 'Unknown',
+          toolInput: raw.item || raw, toolId: baseId,
+        })];
+    }
+  }
+
+  if (raw.type === 'turn_complete') {
+    return [createNormalizedMessage({
+      id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+      kind: 'complete',
+    })];
+  }
+  if (raw.type === 'turn_failed') {
+    return [createNormalizedMessage({
+      id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+      kind: 'error', content: raw.error?.message || 'Turn failed',
+    })];
+  }
+
+  return [];
+}
+
+/**
+ * @type {import('../types.js').ProviderAdapter}
+ */
+export const codexAdapter = {
+  normalizeMessage,
+  /**
+   * Fetch session history from Codex JSONL files.
+   */
+  async fetchHistory(sessionId, opts = {}) {
+    const { limit = null, offset = 0 } = opts;
+
+    let result;
+    try {
+      result = await getCodexSessionMessages(sessionId, limit, offset);
+    } catch (error) {
+      console.warn(`[CodexAdapter] Failed to load session ${sessionId}:`, error.message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    const rawMessages = Array.isArray(result) ? result : (result.messages || []);
+    const total = Array.isArray(result) ? rawMessages.length : (result.total || 0);
+    const hasMore = Array.isArray(result) ? false : Boolean(result.hasMore);
+    const tokenUsage = result.tokenUsage || null;
+
+    const normalized = [];
+    for (const raw of rawMessages) {
+      const entries = normalizeCodexHistoryEntry(raw, sessionId);
+      normalized.push(...entries);
+    }
+
+    // Attach tool results to tool_use messages
+    const toolResultMap = new Map();
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_result' && msg.toolId) {
+        toolResultMap.set(msg.toolId, msg);
+      }
+    }
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_use' && msg.toolId && toolResultMap.has(msg.toolId)) {
+        const tr = toolResultMap.get(msg.toolId);
+        msg.toolResult = { content: tr.content, isError: tr.isError };
+      }
+    }
+
+    return {
+      messages: normalized,
+      total,
+      hasMore,
+      offset,
+      limit,
+      tokenUsage,
+    };
+  },
+};
--- a/server/providers/cursor/adapter.js
+++ b/server/providers/cursor/adapter.js
@@ -0,0 +1,353 @@
+/**
+ * Cursor provider adapter.
+ *
+ * Normalizes Cursor CLI session history into NormalizedMessage format.
+ * @module adapters/cursor
+ */
+
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import { createNormalizedMessage, generateMessageId } from '../types.js';
+
+const PROVIDER = 'cursor';
+
+/**
+ * Load raw blobs from Cursor's SQLite store.db, parse the DAG structure,
+ * and return sorted message blobs in chronological order.
+ * @param {string} sessionId
+ * @param {string} projectPath - Absolute project path (used to compute cwdId hash)
+ * @returns {Promise<Array<{id: string, sequence: number, rowid: number, content: object}>>}
+ */
+async function loadCursorBlobs(sessionId, projectPath) {
+  // Lazy-import sqlite so the module doesn't fail if sqlite3 is unavailable
+  const { default: sqlite3 } = await import('sqlite3');
+  const { open } = await import('sqlite');
+
+  const cwdId = crypto.createHash('md5').update(projectPath || process.cwd()).digest('hex');
+  const storeDbPath = path.join(os.homedir(), '.cursor', 'chats', cwdId, sessionId, 'store.db');
+
+  const db = await open({
+    filename: storeDbPath,
+    driver: sqlite3.Database,
+    mode: sqlite3.OPEN_READONLY,
+  });
+
+  try {
+    const allBlobs = await db.all('SELECT rowid, id, data FROM blobs');
+
+    const blobMap = new Map();
+    const parentRefs = new Map();
+    const childRefs = new Map();
+    const jsonBlobs = [];
+
+    for (const blob of allBlobs) {
+      blobMap.set(blob.id, blob);
+
+      if (blob.data && blob.data[0] === 0x7B) {
+        try {
+          const parsed = JSON.parse(blob.data.toString('utf8'));
+          jsonBlobs.push({ ...blob, parsed });
+        } catch {
+          // skip unparseable blobs
+        }
+      } else if (blob.data) {
+        const parents = [];
+        let i = 0;
+        while (i < blob.data.length - 33) {
+          if (blob.data[i] === 0x0A && blob.data[i + 1] === 0x20) {
+            const parentHash = blob.data.slice(i + 2, i + 34).toString('hex');
+            if (blobMap.has(parentHash)) {
+              parents.push(parentHash);
+            }
+            i += 34;
+          } else {
+            i++;
+          }
+        }
+        if (parents.length > 0) {
+          parentRefs.set(blob.id, parents);
+          for (const parentId of parents) {
+            if (!childRefs.has(parentId)) childRefs.set(parentId, []);
+            childRefs.get(parentId).push(blob.id);
+          }
+        }
+      }
+    }
+
+    // Topological sort (DFS)
+    const visited = new Set();
+    const sorted = [];
+    function visit(nodeId) {
+      if (visited.has(nodeId)) return;
+      visited.add(nodeId);
+      for (const pid of (parentRefs.get(nodeId) || [])) visit(pid);
+      const b = blobMap.get(nodeId);
+      if (b) sorted.push(b);
+    }
+    for (const blob of allBlobs) {
+      if (!parentRefs.has(blob.id)) visit(blob.id);
+    }
+    for (const blob of allBlobs) visit(blob.id);
+
+    // Order JSON blobs by DAG appearance
+    const messageOrder = new Map();
+    let orderIndex = 0;
+    for (const blob of sorted) {
+      if (blob.data && blob.data[0] !== 0x7B) {
+        for (const jb of jsonBlobs) {
+          try {
+            const idBytes = Buffer.from(jb.id, 'hex');
+            if (blob.data.includes(idBytes) && !messageOrder.has(jb.id)) {
+              messageOrder.set(jb.id, orderIndex++);
+            }
+          } catch { /* skip */ }
+        }
+      }
+    }
+
+    const sortedJsonBlobs = jsonBlobs.sort((a, b) => {
+      const oa = messageOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER;
+      const ob = messageOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER;
+      return oa !== ob ? oa - ob : a.rowid - b.rowid;
+    });
+
+    const messages = [];
+    for (let idx = 0; idx < sortedJsonBlobs.length; idx++) {
+      const blob = sortedJsonBlobs[idx];
+      const parsed = blob.parsed;
+      if (!parsed) continue;
+      const role = parsed?.role || parsed?.message?.role;
+      if (role === 'system') continue;
+      messages.push({
+        id: blob.id,
+        sequence: idx + 1,
+        rowid: blob.rowid,
+        content: parsed,
+      });
+    }
+
+    return messages;
+  } finally {
+    await db.close();
+  }
+}
+
+/**
+ * Normalize a realtime NDJSON event from Cursor CLI into NormalizedMessage(s).
+ * History uses normalizeCursorBlobs (SQLite DAG), this handles streaming NDJSON.
+ * @param {object|string} raw - A parsed NDJSON event or a raw text line
+ * @param {string} sessionId
+ * @returns {import('../types.js').NormalizedMessage[]}
+ */
+export function normalizeMessage(raw, sessionId) {
+  // Structured assistant message with content array
+  if (raw && typeof raw === 'object' && raw.type === 'assistant' && raw.message?.content?.[0]?.text) {
+    return [createNormalizedMessage({ kind: 'stream_delta', content: raw.message.content[0].text, sessionId, provider: PROVIDER })];
+  }
+  // Plain string line (non-JSON output)
+  if (typeof raw === 'string' && raw.trim()) {
+    return [createNormalizedMessage({ kind: 'stream_delta', content: raw, sessionId, provider: PROVIDER })];
+  }
+  return [];
+}
+
+/**
+ * @type {import('../types.js').ProviderAdapter}
+ */
+export const cursorAdapter = {
+  normalizeMessage,
+  /**
+   * Fetch session history for Cursor from SQLite store.db.
+   */
+  async fetchHistory(sessionId, opts = {}) {
+    const { projectPath = '', limit = null, offset = 0 } = opts;
+
+    try {
+      const blobs = await loadCursorBlobs(sessionId, projectPath);
+      const allNormalized = cursorAdapter.normalizeCursorBlobs(blobs, sessionId);
+
+      // Apply pagination
+      if (limit !== null && limit > 0) {
+        const start = offset;
+        const page = allNormalized.slice(start, start + limit);
+        return {
+          messages: page,
+          total: allNormalized.length,
+          hasMore: start + limit < allNormalized.length,
+          offset,
+          limit,
+        };
+      }
+
+      return {
+        messages: allNormalized,
+        total: allNormalized.length,
+        hasMore: false,
+        offset: 0,
+        limit: null,
+      };
+    } catch (error) {
+      // DB doesn't exist or is unreadable — return empty
+      console.warn(`[CursorAdapter] Failed to load session ${sessionId}:`, error.message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+  },
+
+  /**
+   * Normalize raw Cursor blob messages into NormalizedMessage[].
+   * @param {any[]} blobs - Raw cursor blobs from store.db ({id, sequence, rowid, content})
+   * @param {string} sessionId
+   * @returns {import('../types.js').NormalizedMessage[]}
+   */
+  normalizeCursorBlobs(blobs, sessionId) {
+    const messages = [];
+    const toolUseMap = new Map();
+
+    // Use a fixed base timestamp so messages have stable, monotonically-increasing
+    // timestamps based on their sequence number rather than wall-clock time.
+    const baseTime = Date.now();
+
+    for (let i = 0; i < blobs.length; i++) {
+      const blob = blobs[i];
+      const content = blob.content;
+      const ts = new Date(baseTime + (blob.sequence ?? i) * 100).toISOString();
+      const baseId = blob.id || generateMessageId('cursor');
+
+      try {
+        if (!content?.role || !content?.content) {
+          // Try nested message format
+          if (content?.message?.role && content?.message?.content) {
+            if (content.message.role === 'system') continue;
+            const role = content.message.role === 'user' ? 'user' : 'assistant';
+            let text = '';
+            if (Array.isArray(content.message.content)) {
+              text = content.message.content
+                .map(p => typeof p === 'string' ? p : p?.text || '')
+                .filter(Boolean)
+                .join('\n');
+            } else if (typeof content.message.content === 'string') {
+              text = content.message.content;
+            }
+            if (text?.trim()) {
+              messages.push(createNormalizedMessage({
+                id: baseId,
+                sessionId,
+                timestamp: ts,
+                provider: PROVIDER,
+                kind: 'text',
+                role,
+                content: text,
+                sequence: blob.sequence,
+                rowid: blob.rowid,
+              }));
+            }
+          }
+          continue;
+        }
+
+        if (content.role === 'system') continue;
+
+        // Tool results
+        if (content.role === 'tool') {
+          const toolItems = Array.isArray(content.content) ? content.content : [];
+          for (const item of toolItems) {
+            if (item?.type !== 'tool-result') continue;
+            const toolCallId = item.toolCallId || content.id;
+            messages.push(createNormalizedMessage({
+              id: `${baseId}_tr`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'tool_result',
+              toolId: toolCallId,
+              content: item.result || '',
+              isError: false,
+            }));
+          }
+          continue;
+        }
+
+        const role = content.role === 'user' ? 'user' : 'assistant';
+
+        if (Array.isArray(content.content)) {
+          for (let partIdx = 0; partIdx < content.content.length; partIdx++) {
+            const part = content.content[partIdx];
+
+            if (part?.type === 'text' && part?.text) {
+              messages.push(createNormalizedMessage({
+                id: `${baseId}_${partIdx}`,
+                sessionId,
+                timestamp: ts,
+                provider: PROVIDER,
+                kind: 'text',
+                role,
+                content: part.text,
+                sequence: blob.sequence,
+                rowid: blob.rowid,
+              }));
+            } else if (part?.type === 'reasoning' && part?.text) {
+              messages.push(createNormalizedMessage({
+                id: `${baseId}_${partIdx}`,
+                sessionId,
+                timestamp: ts,
+                provider: PROVIDER,
+                kind: 'thinking',
+                content: part.text,
+              }));
+            } else if (part?.type === 'tool-call' || part?.type === 'tool_use') {
+              const toolName = (part.toolName || part.name || 'Unknown Tool') === 'ApplyPatch'
+                ? 'Edit' : (part.toolName || part.name || 'Unknown Tool');
+              const toolId = part.toolCallId || part.id || `tool_${i}_${partIdx}`;
+              messages.push(createNormalizedMessage({
+                id: `${baseId}_${partIdx}`,
+                sessionId,
+                timestamp: ts,
+                provider: PROVIDER,
+                kind: 'tool_use',
+                toolName,
+                toolInput: part.args || part.input,
+                toolId,
+              }));
+              toolUseMap.set(toolId, messages[messages.length - 1]);
+            }
+          }
+        } else if (typeof content.content === 'string' && content.content.trim()) {
+          messages.push(createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'text',
+            role,
+            content: content.content,
+            sequence: blob.sequence,
+            rowid: blob.rowid,
+          }));
+        }
+      } catch (error) {
+        console.warn('Error normalizing cursor blob:', error);
+      }
+    }
+
+    // Attach tool results to tool_use messages
+    for (const msg of messages) {
+      if (msg.kind === 'tool_result' && msg.toolId && toolUseMap.has(msg.toolId)) {
+        const toolUse = toolUseMap.get(msg.toolId);
+        toolUse.toolResult = {
+          content: msg.content,
+          isError: msg.isError,
+        };
+      }
+    }
+
+    // Sort by sequence/rowid
+    messages.sort((a, b) => {
+      if (a.sequence !== undefined && b.sequence !== undefined) return a.sequence - b.sequence;
+      if (a.rowid !== undefined && b.rowid !== undefined) return a.rowid - b.rowid;
+      return new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime();
+    });
+
+    return messages;
+  },
+};
--- a/server/providers/gemini/adapter.js
+++ b/server/providers/gemini/adapter.js
@@ -0,0 +1,186 @@
+/**
+ * Gemini provider adapter.
+ *
+ * Normalizes Gemini CLI session history into NormalizedMessage format.
+ * @module adapters/gemini
+ */
+
+import sessionManager from '../../sessionManager.js';
+import { getGeminiCliSessionMessages } from '../../projects.js';
+import { createNormalizedMessage, generateMessageId } from '../types.js';
+
+const PROVIDER = 'gemini';
+
+/**
+ * Normalize a realtime NDJSON event from Gemini CLI into NormalizedMessage(s).
+ * Handles: message (delta/final), tool_use, tool_result, result, error.
+ * @param {object} raw - A parsed NDJSON event
+ * @param {string} sessionId
+ * @returns {import('../types.js').NormalizedMessage[]}
+ */
+export function normalizeMessage(raw, sessionId) {
+  const ts = raw.timestamp || new Date().toISOString();
+  const baseId = raw.uuid || generateMessageId('gemini');
+
+  if (raw.type === 'message' && raw.role === 'assistant') {
+    const content = raw.content || '';
+    const msgs = [];
+    if (content) {
+      msgs.push(createNormalizedMessage({ id: baseId, sessionId, timestamp: ts, provider: PROVIDER, kind: 'stream_delta', content }));
+    }
+    // If not a delta, also send stream_end
+    if (raw.delta !== true) {
+      msgs.push(createNormalizedMessage({ sessionId, timestamp: ts, provider: PROVIDER, kind: 'stream_end' }));
+    }
+    return msgs;
+  }
+
+  if (raw.type === 'tool_use') {
+    return [createNormalizedMessage({
+      id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+      kind: 'tool_use', toolName: raw.tool_name, toolInput: raw.parameters || {},
+      toolId: raw.tool_id || baseId,
+    })];
+  }
+
+  if (raw.type === 'tool_result') {
+    return [createNormalizedMessage({
+      id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+      kind: 'tool_result', toolId: raw.tool_id || '',
+      content: raw.output === undefined ? '' : String(raw.output),
+      isError: raw.status === 'error',
+    })];
+  }
+
+  if (raw.type === 'result') {
+    const msgs = [createNormalizedMessage({ sessionId, timestamp: ts, provider: PROVIDER, kind: 'stream_end' })];
+    if (raw.stats?.total_tokens) {
+      msgs.push(createNormalizedMessage({
+        sessionId, timestamp: ts, provider: PROVIDER,
+        kind: 'status', text: 'Complete', tokens: raw.stats.total_tokens, canInterrupt: false,
+      }));
+    }
+    return msgs;
+  }
+
+  if (raw.type === 'error') {
+    return [createNormalizedMessage({
+      id: baseId, sessionId, timestamp: ts, provider: PROVIDER,
+      kind: 'error', content: raw.error || raw.message || 'Unknown Gemini streaming error',
+    })];
+  }
+
+  return [];
+}
+
+/**
+ * @type {import('../types.js').ProviderAdapter}
+ */
+export const geminiAdapter = {
+  normalizeMessage,
+  /**
+   * Fetch session history for Gemini.
+   * First tries in-memory session manager, then falls back to CLI sessions on disk.
+   */
+  async fetchHistory(sessionId, opts = {}) {
+    let rawMessages;
+    try {
+      rawMessages = sessionManager.getSessionMessages(sessionId);
+
+      // Fallback to Gemini CLI sessions on disk
+      if (rawMessages.length === 0) {
+        rawMessages = await getGeminiCliSessionMessages(sessionId);
+      }
+    } catch (error) {
+      console.warn(`[GeminiAdapter] Failed to load session ${sessionId}:`, error.message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    const normalized = [];
+    for (let i = 0; i < rawMessages.length; i++) {
+      const raw = rawMessages[i];
+      const ts = raw.timestamp || new Date().toISOString();
+      const baseId = raw.uuid || generateMessageId('gemini');
+
+      // sessionManager format: { type: 'message', message: { role, content }, timestamp }
+      // CLI format: { role: 'user'|'gemini'|'assistant', content: string|array }
+      const role = raw.message?.role || raw.role;
+      const content = raw.message?.content || raw.content;
+
+      if (!role || !content) continue;
+
+      const normalizedRole = (role === 'user') ? 'user' : 'assistant';
+
+      if (Array.isArray(content)) {
+        for (let partIdx = 0; partIdx < content.length; partIdx++) {
+          const part = content[partIdx];
+          if (part.type === 'text' && part.text) {
+            normalized.push(createNormalizedMessage({
+              id: `${baseId}_${partIdx}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'text',
+              role: normalizedRole,
+              content: part.text,
+            }));
+          } else if (part.type === 'tool_use') {
+            normalized.push(createNormalizedMessage({
+              id: `${baseId}_${partIdx}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'tool_use',
+              toolName: part.name,
+              toolInput: part.input,
+              toolId: part.id || generateMessageId('gemini_tool'),
+            }));
+          } else if (part.type === 'tool_result') {
+            normalized.push(createNormalizedMessage({
+              id: `${baseId}_${partIdx}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'tool_result',
+              toolId: part.tool_use_id || '',
+              content: part.content === undefined ? '' : String(part.content),
+              isError: Boolean(part.is_error),
+            }));
+          }
+        }
+      } else if (typeof content === 'string' && content.trim()) {
+        normalized.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp: ts,
+          provider: PROVIDER,
+          kind: 'text',
+          role: normalizedRole,
+          content,
+        }));
+      }
+    }
+
+    // Attach tool results to tool_use messages
+    const toolResultMap = new Map();
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_result' && msg.toolId) {
+        toolResultMap.set(msg.toolId, msg);
+      }
+    }
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_use' && msg.toolId && toolResultMap.has(msg.toolId)) {
+        const tr = toolResultMap.get(msg.toolId);
+        msg.toolResult = { content: tr.content, isError: tr.isError };
+      }
+    }
+
+    return {
+      messages: normalized,
+      total: normalized.length,
+      hasMore: false,
+      offset: 0,
+      limit: null,
+    };
+  },
+};
--- a/server/providers/registry.js
+++ b/server/providers/registry.js
@@ -0,0 +1,44 @@
+/**
+ * Provider Registry
+ *
+ * Centralizes provider adapter lookup. All code that needs a provider adapter
+ * should go through this registry instead of importing individual adapters directly.
+ *
+ * @module providers/registry
+ */
+
+import { claudeAdapter } from './claude/adapter.js';
+import { cursorAdapter } from './cursor/adapter.js';
+import { codexAdapter } from './codex/adapter.js';
+import { geminiAdapter } from './gemini/adapter.js';
+
+/**
+ * @typedef {import('./types.js').ProviderAdapter} ProviderAdapter
+ * @typedef {import('./types.js').SessionProvider} SessionProvider
+ */
+
+/** @type {Map<string, ProviderAdapter>} */
+const providers = new Map();
+
+// Register built-in providers
+providers.set('claude', claudeAdapter);
+providers.set('cursor', cursorAdapter);
+providers.set('codex', codexAdapter);
+providers.set('gemini', geminiAdapter);
+
+/**
+ * Get a provider adapter by name.
+ * @param {string} name - Provider name (e.g., 'claude', 'cursor', 'codex', 'gemini')
+ * @returns {ProviderAdapter | undefined}
+ */
+export function getProvider(name) {
+  return providers.get(name);
+}
+
+/**
+ * Get all registered provider names.
+ * @returns {string[]}
+ */
+export function getAllProviders() {
+  return Array.from(providers.keys());
+}
--- a/server/providers/types.js
+++ b/server/providers/types.js
@@ -0,0 +1,119 @@
+/**
+ * Provider Types & Interface
+ *
+ * Defines the normalized message format and the provider adapter interface.
+ * All providers normalize their native formats into NormalizedMessage
+ * before sending over REST or WebSocket.
+ *
+ * @module providers/types
+ */
+
+// ─── Session Provider ────────────────────────────────────────────────────────
+
+/**
+ * @typedef {'claude' | 'cursor' | 'codex' | 'gemini'} SessionProvider
+ */
+
+// ─── Message Kind ────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {'text' | 'tool_use' | 'tool_result' | 'thinking' | 'stream_delta' | 'stream_end'
+ *   | 'error' | 'complete' | 'status' | 'permission_request' | 'permission_cancelled'
+ *   | 'session_created' | 'interactive_prompt' | 'task_notification'} MessageKind
+ */
+
+// ─── NormalizedMessage ───────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} NormalizedMessage
+ * @property {string} id - Unique message id (for dedup between server + realtime)
+ * @property {string} sessionId
+ * @property {string} timestamp - ISO 8601
+ * @property {SessionProvider} provider
+ * @property {MessageKind} kind
+ *
+ * Additional fields depending on kind:
+ * - text:                 role ('user'|'assistant'), content, images?
+ * - tool_use:             toolName, toolInput, toolId
+ * - tool_result:          toolId, content, isError
+ * - thinking:             content
+ * - stream_delta:         content
+ * - stream_end:           (no extra fields)
+ * - error:                content
+ * - complete:             (no extra fields)
+ * - status:               text, tokens?, canInterrupt?
+ * - permission_request:   requestId, toolName, input, context?
+ * - permission_cancelled: requestId
+ * - session_created:      newSessionId
+ * - interactive_prompt:   content
+ * - task_notification:    status, summary
+ */
+
+// ─── Fetch History ───────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} FetchHistoryOptions
+ * @property {string} [projectName] - Project name (required for Claude)
+ * @property {string} [projectPath] - Absolute project path (required for Cursor cwdId hash)
+ * @property {number|null} [limit] - Page size (null = all messages)
+ * @property {number} [offset] - Pagination offset (default: 0)
+ */
+
+/**
+ * @typedef {Object} FetchHistoryResult
+ * @property {NormalizedMessage[]} messages - Normalized messages
+ * @property {number} total - Total number of messages in the session
+ * @property {boolean} hasMore - Whether more messages exist before the current page
+ * @property {number} offset - Current offset
+ * @property {number|null} limit - Page size used
+ * @property {object} [tokenUsage] - Token usage data (provider-specific)
+ */
+
+// ─── Provider Adapter Interface ──────────────────────────────────────────────
+
+/**
+ * Every provider adapter MUST implement this interface.
+ *
+ * @typedef {Object} ProviderAdapter
+ *
+ * @property {(sessionId: string, opts?: FetchHistoryOptions) => Promise<FetchHistoryResult>} fetchHistory
+ *   Read persisted session messages from disk/database and return them as NormalizedMessage[].
+ *   The backend calls this from the unified GET /api/sessions/:id/messages endpoint.
+ *
+ *   Provider implementations:
+ *   - Claude: reads ~/.claude/projects/{projectName}/*.jsonl
+ *   - Cursor: reads from SQLite store.db (via normalizeCursorBlobs helper)
+ *   - Codex:  reads ~/.codex/sessions/*.jsonl
+ *   - Gemini: reads from in-memory sessionManager or ~/.gemini/tmp/ JSON files
+ *
+ * @property {(raw: any, sessionId: string) => NormalizedMessage[]} normalizeMessage
+ *   Normalize a provider-specific event (JSONL entry or live SDK event) into NormalizedMessage[].
+ *   Used by provider files to convert both history and realtime events.
+ */
+
+// ─── Runtime Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Generate a unique message ID.
+ * Uses crypto.randomUUID() to avoid collisions across server restarts and workers.
+ * @param {string} [prefix='msg'] - Optional prefix
+ * @returns {string}
+ */
+export function generateMessageId(prefix = 'msg') {
+  return `${prefix}_${crypto.randomUUID()}`;
+}
+
+/**
+ * Create a NormalizedMessage with common fields pre-filled.
+ * @param {Partial<NormalizedMessage> & {kind: MessageKind, provider: SessionProvider}} fields
+ * @returns {NormalizedMessage}
+ */
+export function createNormalizedMessage(fields) {
+  return {
+    ...fields,
+    id: fields.id || generateMessageId(fields.kind),
+    sessionId: fields.sessionId || '',
+    timestamp: fields.timestamp || new Date().toISOString(),
+    provider: fields.provider,
+  };
+}
--- a/server/providers/utils.js
+++ b/server/providers/utils.js
@@ -0,0 +1,29 @@
+/**
+ * Shared provider utilities.
+ *
+ * @module providers/utils
+ */
+
+/**
+ * Prefixes that indicate internal/system content which should be hidden from the UI.
+ * @type {readonly string[]}
+ */
+export const INTERNAL_CONTENT_PREFIXES = Object.freeze([
+  '<command-name>',
+  '<command-message>',
+  '<command-args>',
+  '<local-command-stdout>',
+  '<system-reminder>',
+  'Caveat:',
+  'This session is being continued from a previous',
+  '[Request interrupted',
+]);
+
+/**
+ * Check if user text content is internal/system that should be skipped.
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function isInternalContent(content) {
+  return INTERNAL_CONTENT_PREFIXES.some(prefix => content.startsWith(prefix));
+}
--- a/server/routes/codex.js
+++ b/server/routes/codex.js
@@ -4,7 +4,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import TOML from '@iarna/toml';
-import { getCodexSessions, getCodexSessionMessages, deleteCodexSession } from '../projects.js';
+import { getCodexSessions, deleteCodexSession } from '../projects.js';
 import { applyCustomSessionNames, sessionNamesDb } from '../database/db.js';

 const router = express.Router();
@@ -68,24 +68,6 @@ router.get('/sessions', async (req, res) => {
  }
 });

-router.get('/sessions/:sessionId/messages', async (req, res) => {
-  try {
-    const { sessionId } = req.params;
-    const { limit, offset } = req.query;
-
-    const result = await getCodexSessionMessages(
-      sessionId,
-      limit ? parseInt(limit, 10) : null,
-      offset ? parseInt(offset, 10) : 0
-    );
-
-    res.json({ success: true, ...result });
-  } catch (error) {
-    console.error('Error fetching Codex session messages:', error);
-    res.status(500).json({ success: false, error: error.message });
-  }
-});
-
 router.delete('/sessions/:sessionId', async (req, res) => {
  try {
    const { sessionId } = req.params;
--- a/server/routes/gemini.js
+++ b/server/routes/gemini.js
@@ -1,39 +1,9 @@
 import express from 'express';
 import sessionManager from '../sessionManager.js';
 import { sessionNamesDb } from '../database/db.js';
-import { getGeminiCliSessionMessages } from '../projects.js';

 const router = express.Router();

-router.get('/sessions/:sessionId/messages', async (req, res) => {
-    try {
-        const { sessionId } = req.params;
-
-        if (!sessionId || typeof sessionId !== 'string' || !/^[a-zA-Z0-9_.-]{1,100}$/.test(sessionId)) {
-            return res.status(400).json({ success: false, error: 'Invalid session ID format' });
-        }
-
-        let messages = sessionManager.getSessionMessages(sessionId);
-
-        // Fallback to Gemini CLI sessions on disk
-        if (messages.length === 0) {
-            messages = await getGeminiCliSessionMessages(sessionId);
-        }
-
-        res.json({
-            success: true,
-            messages: messages,
-            total: messages.length,
-            hasMore: false,
-            offset: 0,
-            limit: messages.length
-        });
-    } catch (error) {
-        console.error('Error fetching Gemini session messages:', error);
-        res.status(500).json({ success: false, error: error.message });
-    }
-});
-
 router.delete('/sessions/:sessionId', async (req, res) => {
    try {
        const { sessionId } = req.params;
--- a/server/routes/messages.js
+++ b/server/routes/messages.js
@@ -0,0 +1,61 @@
+/**
+ * Unified messages endpoint.
+ *
+ * GET /api/sessions/:sessionId/messages?provider=claude&projectName=foo&limit=50&offset=0
+ *
+ * Replaces the four provider-specific session message endpoints with a single route
+ * that delegates to the appropriate adapter via the provider registry.
+ *
+ * @module routes/messages
+ */
+
+import express from 'express';
+import { getProvider, getAllProviders } from '../providers/registry.js';
+
+const router = express.Router();
+
+/**
+ * GET /api/sessions/:sessionId/messages
+ *
+ * Auth: authenticateToken applied at mount level in index.js
+ *
+ * Query params:
+ *   provider    - 'claude' | 'cursor' | 'codex' | 'gemini' (default: 'claude')
+ *   projectName - required for claude provider
+ *   projectPath - required for cursor provider (absolute path used for cwdId hash)
+ *   limit       - page size (omit or null for all)
+ *   offset      - pagination offset (default: 0)
+ */
+router.get('/:sessionId/messages', async (req, res) => {
+  try {
+    const { sessionId } = req.params;
+    const provider = req.query.provider || 'claude';
+    const projectName = req.query.projectName || '';
+    const projectPath = req.query.projectPath || '';
+    const limitParam = req.query.limit;
+    const limit = limitParam !== undefined && limitParam !== null && limitParam !== ''
+      ? parseInt(limitParam, 10)
+      : null;
+    const offset = parseInt(req.query.offset || '0', 10);
+
+    const adapter = getProvider(provider);
+    if (!adapter) {
+      const available = getAllProviders().join(', ');
+      return res.status(400).json({ error: `Unknown provider: ${provider}. Available: ${available}` });
+    }
+
+    const result = await adapter.fetchHistory(sessionId, {
+      projectName,
+      projectPath,
+      limit,
+      offset,
+    });
+
+    return res.json(result);
+  } catch (error) {
+    console.error('Error fetching unified messages:', error);
+    return res.status(500).json({ error: 'Failed to fetch messages' });
+  }
+});
+
+export default router;
--- a/src/components/chat/hooks/useChatComposerState.ts
+++ b/src/components/chat/hooks/useChatComposerState.ts
@@ -52,8 +52,9 @@ interface UseChatComposerStateArgs {
  onShowSettings?: () => void;
  pendingViewSessionRef: { current: PendingViewSession | null };
  scrollToBottom: () => void;
-  setChatMessages: Dispatch<SetStateAction<ChatMessage[]>>;
-  setSessionMessages?: Dispatch<SetStateAction<any[]>>;
+  addMessage: (msg: ChatMessage) => void;
+  clearMessages: () => void;
+  rewindMessages: (count: number) => void;
  setIsLoading: (loading: boolean) => void;
  setCanAbortSession: (canAbort: boolean) => void;
  setClaudeStatus: (status: { text: string; tokens: number; can_interrupt: boolean } | null) => void;
@@ -123,8 +124,9 @@ export function useChatComposerState({
  onShowSettings,
  pendingViewSessionRef,
  scrollToBottom,
-  setChatMessages,
-  setSessionMessages,
+  addMessage,
+  clearMessages,
+  rewindMessages,
  setIsLoading,
  setCanAbortSession,
  setClaudeStatus,
@@ -155,69 +157,50 @@ export function useChatComposerState({
      const { action, data } = result;
      switch (action) {
        case 'clear':
-          setChatMessages([]);
-          setSessionMessages?.([]);
+          clearMessages();
          break;

        case 'help':
-          setChatMessages((previous) => [
-            ...previous,
-            {
-              type: 'assistant',
-              content: data.content,
-              timestamp: Date.now(),
-            },
-          ]);
+          addMessage({
+            type: 'assistant',
+            content: data.content,
+            timestamp: Date.now(),
+          });
          break;

        case 'model':
-          setChatMessages((previous) => [
-            ...previous,
-            {
-              type: 'assistant',
-              content: `**Current Model**: ${data.current.model}\n\n**Available Models**:\n\nClaude: ${data.available.claude.join(', ')}\n\nCursor: ${data.available.cursor.join(', ')}`,
-              timestamp: Date.now(),
-            },
-          ]);
+          addMessage({
+            type: 'assistant',
+            content: `**Current Model**: ${data.current.model}\n\n**Available Models**:\n\nClaude: ${data.available.claude.join(', ')}\n\nCursor: ${data.available.cursor.join(', ')}`,
+            timestamp: Date.now(),
+          });
          break;

        case 'cost': {
          const costMessage = `**Token Usage**: ${data.tokenUsage.used.toLocaleString()} / ${data.tokenUsage.total.toLocaleString()} (${data.tokenUsage.percentage}%)\n\n**Estimated Cost**:\n- Input: $${data.cost.input}\n- Output: $${data.cost.output}\n- **Total**: $${data.cost.total}\n\n**Model**: ${data.model}`;
-          setChatMessages((previous) => [
-            ...previous,
-            { type: 'assistant', content: costMessage, timestamp: Date.now() },
-          ]);
+          addMessage({ type: 'assistant', content: costMessage, timestamp: Date.now() });
          break;
        }

        case 'status': {
          const statusMessage = `**System Status**\n\n- Version: ${data.version}\n- Uptime: ${data.uptime}\n- Model: ${data.model}\n- Provider: ${data.provider}\n- Node.js: ${data.nodeVersion}\n- Platform: ${data.platform}`;
-          setChatMessages((previous) => [
-            ...previous,
-            { type: 'assistant', content: statusMessage, timestamp: Date.now() },
-          ]);
+          addMessage({ type: 'assistant', content: statusMessage, timestamp: Date.now() });
          break;
        }

        case 'memory':
          if (data.error) {
-            setChatMessages((previous) => [
-              ...previous,
-              {
-                type: 'assistant',
-                content: `⚠️ ${data.message}`,
-                timestamp: Date.now(),
-              },
-            ]);
+            addMessage({
+              type: 'assistant',
+              content: `Warning: ${data.message}`,
+              timestamp: Date.now(),
+            });
          } else {
-            setChatMessages((previous) => [
-              ...previous,
-              {
-                type: 'assistant',
-                content: `📝 ${data.message}\n\nPath: \`${data.path}\``,
-                timestamp: Date.now(),
-              },
-            ]);
+            addMessage({
+              type: 'assistant',
+              content: `${data.message}\n\nPath: \`${data.path}\``,
+              timestamp: Date.now(),
+            });
            if (data.exists && onFileOpen) {
              onFileOpen(data.path);
            }
@@ -230,24 +213,18 @@ export function useChatComposerState({

        case 'rewind':
          if (data.error) {
-            setChatMessages((previous) => [
-              ...previous,
-              {
-                type: 'assistant',
-                content: `⚠️ ${data.message}`,
-                timestamp: Date.now(),
-              },
-            ]);
+            addMessage({
+              type: 'assistant',
+              content: `Warning: ${data.message}`,
+              timestamp: Date.now(),
+            });
          } else {
-            setChatMessages((previous) => previous.slice(0, -data.steps * 2));
-            setChatMessages((previous) => [
-              ...previous,
-              {
-                type: 'assistant',
-                content: `⏪ ${data.message}`,
-                timestamp: Date.now(),
-              },
-            ]);
+            rewindMessages(data.steps * 2);
+            addMessage({
+              type: 'assistant',
+              content: `Rewound ${data.steps} step(s). ${data.message}`,
+              timestamp: Date.now(),
+            });
          }
          break;

@@ -255,7 +232,7 @@ export function useChatComposerState({
          console.warn('Unknown built-in command action:', action);
      }
    },
-    [onFileOpen, onShowSettings, setChatMessages, setSessionMessages],
+    [onFileOpen, onShowSettings, addMessage, clearMessages, rewindMessages],
  );

  const handleCustomCommand = useCallback(async (result: CommandExecutionResult) => {
@@ -266,14 +243,11 @@ export function useChatComposerState({
        'This command contains bash commands that will be executed. Do you want to proceed?',
      );
      if (!confirmed) {
-        setChatMessages((previous) => [
-          ...previous,
-          {
-            type: 'assistant',
-            content: '❌ Command execution cancelled',
-            timestamp: Date.now(),
-          },
-        ]);
+        addMessage({
+          type: 'assistant',
+          content: 'Command execution cancelled',
+          timestamp: Date.now(),
+        });
        return;
      }
    }
@@ -288,7 +262,7 @@ export function useChatComposerState({
        handleSubmitRef.current(createFakeSubmitEvent());
      }
    }, 0);
-  }, [setChatMessages]);
+  }, [addMessage]);

  const executeCommand = useCallback(
    async (command: SlashCommand, rawInput?: string) => {
@@ -346,14 +320,11 @@ export function useChatComposerState({
      } catch (error) {
        const message = error instanceof Error ? error.message : 'Unknown error';
        console.error('Error executing command:', error);
-        setChatMessages((previous) => [
-          ...previous,
-          {
-            type: 'assistant',
-            content: `Error executing command: ${message}`,
-            timestamp: Date.now(),
-          },
-        ]);
+        addMessage({
+          type: 'assistant',
+          content: `Error executing command: ${message}`,
+          timestamp: Date.now(),
+        });
      }
    },
    [
@@ -367,7 +338,7 @@ export function useChatComposerState({
      input,
      provider,
      selectedProject,
-      setChatMessages,
+      addMessage,
      tokenBudget,
    ],
  );
@@ -547,18 +518,19 @@ export function useChatComposerState({
        } catch (error) {
          const message = error instanceof Error ? error.message : 'Unknown error';
          console.error('Image upload failed:', error);
-          setChatMessages((previous) => [
-            ...previous,
-            {
-              type: 'error',
-              content: `Failed to upload images: ${message}`,
-              timestamp: new Date(),
-            },
-          ]);
+          addMessage({
+            type: 'error',
+            content: `Failed to upload images: ${message}`,
+            timestamp: new Date(),
+          });
          return;
        }
      }

+      const effectiveSessionId =
+        currentSessionId || selectedSession?.id || sessionStorage.getItem('cursorSessionId');
+      const sessionToActivate = effectiveSessionId || `new-session-${Date.now()}`;
+
      const userMessage: ChatMessage = {
        type: 'user',
        content: currentInput,
@@ -566,7 +538,7 @@ export function useChatComposerState({
        timestamp: new Date(),
      };

-      setChatMessages((previous) => [...previous, userMessage]);
+      addMessage(userMessage);
      setIsLoading(true); // Processing banner starts
      setCanAbortSession(true);
      setClaudeStatus({
@@ -578,10 +550,6 @@ export function useChatComposerState({
      setIsUserScrolledUp(false);
      setTimeout(() => scrollToBottom(), 100);

-      const effectiveSessionId =
-        currentSessionId || selectedSession?.id || sessionStorage.getItem('cursorSessionId');
-      const sessionToActivate = effectiveSessionId || `new-session-${Date.now()}`;
-
      if (!effectiveSessionId && !selectedSession?.id) {
        if (typeof window !== 'undefined') {
          // Reset stale pending IDs from previous interrupted runs before creating a new one.
@@ -723,7 +691,7 @@ export function useChatComposerState({
      selectedProject,
      sendMessage,
      setCanAbortSession,
-      setChatMessages,
+      addMessage,
      setClaudeStatus,
      setIsLoading,
      setIsUserScrolledUp,
--- a/src/components/chat/hooks/useChatMessages.ts
+++ b/src/components/chat/hooks/useChatMessages.ts
@@ -0,0 +1,183 @@
+/**
+ * Message normalization utilities.
+ * Converts NormalizedMessage[] from the session store into ChatMessage[] for the UI.
+ */
+
+import type { NormalizedMessage } from '../../../stores/useSessionStore';
+import type { ChatMessage, SubagentChildTool } from '../types/types';
+import { decodeHtmlEntities, unescapeWithMathProtection, formatUsageLimitText } from '../utils/chatFormatting';
+
+/**
+ * Convert NormalizedMessage[] from the session store into ChatMessage[]
+ * that the existing UI components expect.
+ *
+ * Internal/system content (e.g. <system-reminder>, <command-name>) is already
+ * filtered server-side by the Claude adapter (server/providers/utils.js).
+ */
+export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMessage[] {
+  const converted: ChatMessage[] = [];
+
+  // First pass: collect tool results for attachment
+  const toolResultMap = new Map<string, NormalizedMessage>();
+  for (const msg of messages) {
+    if (msg.kind === 'tool_result' && msg.toolId) {
+      toolResultMap.set(msg.toolId, msg);
+    }
+  }
+
+  for (const msg of messages) {
+    switch (msg.kind) {
+      case 'text': {
+        const content = msg.content || '';
+        if (!content.trim()) continue;
+
+        if (msg.role === 'user') {
+          // Parse task notifications
+          const taskNotifRegex = /<task-notification>\s*<task-id>[^<]*<\/task-id>\s*<output-file>[^<]*<\/output-file>\s*<status>([^<]*)<\/status>\s*<summary>([^<]*)<\/summary>\s*<\/task-notification>/g;
+          const taskNotifMatch = taskNotifRegex.exec(content);
+          if (taskNotifMatch) {
+            converted.push({
+              type: 'assistant',
+              content: taskNotifMatch[2]?.trim() || 'Background task finished',
+              timestamp: msg.timestamp,
+              isTaskNotification: true,
+              taskStatus: taskNotifMatch[1]?.trim() || 'completed',
+            });
+          } else {
+            converted.push({
+              type: 'user',
+              content: unescapeWithMathProtection(decodeHtmlEntities(content)),
+              timestamp: msg.timestamp,
+            });
+          }
+        } else {
+          let text = decodeHtmlEntities(content);
+          text = unescapeWithMathProtection(text);
+          text = formatUsageLimitText(text);
+          converted.push({
+            type: 'assistant',
+            content: text,
+            timestamp: msg.timestamp,
+          });
+        }
+        break;
+      }
+
+      case 'tool_use': {
+        const tr = msg.toolResult || (msg.toolId ? toolResultMap.get(msg.toolId) : null);
+        const isSubagentContainer = msg.toolName === 'Task';
+
+        // Build child tools from subagentTools
+        const childTools: SubagentChildTool[] = [];
+        if (isSubagentContainer && msg.subagentTools && Array.isArray(msg.subagentTools)) {
+          for (const tool of msg.subagentTools as any[]) {
+            childTools.push({
+              toolId: tool.toolId,
+              toolName: tool.toolName,
+              toolInput: tool.toolInput,
+              toolResult: tool.toolResult || null,
+              timestamp: new Date(tool.timestamp || Date.now()),
+            });
+          }
+        }
+
+        const toolResult = tr
+          ? {
+              content: typeof tr.content === 'string' ? tr.content : JSON.stringify(tr.content),
+              isError: Boolean(tr.isError),
+              toolUseResult: (tr as any).toolUseResult,
+            }
+          : null;
+
+        converted.push({
+          type: 'assistant',
+          content: '',
+          timestamp: msg.timestamp,
+          isToolUse: true,
+          toolName: msg.toolName,
+          toolInput: typeof msg.toolInput === 'string' ? msg.toolInput : JSON.stringify(msg.toolInput ?? '', null, 2),
+          toolId: msg.toolId,
+          toolResult,
+          isSubagentContainer,
+          subagentState: isSubagentContainer
+            ? {
+                childTools,
+                currentToolIndex: childTools.length > 0 ? childTools.length - 1 : -1,
+                isComplete: Boolean(toolResult),
+              }
+            : undefined,
+        });
+        break;
+      }
+
+      case 'thinking':
+        if (msg.content?.trim()) {
+          converted.push({
+            type: 'assistant',
+            content: unescapeWithMathProtection(msg.content),
+            timestamp: msg.timestamp,
+            isThinking: true,
+          });
+        }
+        break;
+
+      case 'error':
+        converted.push({
+          type: 'error',
+          content: msg.content || 'Unknown error',
+          timestamp: msg.timestamp,
+        });
+        break;
+
+      case 'interactive_prompt':
+        converted.push({
+          type: 'assistant',
+          content: msg.content || '',
+          timestamp: msg.timestamp,
+          isInteractivePrompt: true,
+        });
+        break;
+
+      case 'task_notification':
+        converted.push({
+          type: 'assistant',
+          content: msg.summary || 'Background task update',
+          timestamp: msg.timestamp,
+          isTaskNotification: true,
+          taskStatus: msg.status || 'completed',
+        });
+        break;
+
+      case 'stream_delta':
+        if (msg.content) {
+          converted.push({
+            type: 'assistant',
+            content: msg.content,
+            timestamp: msg.timestamp,
+            isStreaming: true,
+          });
+        }
+        break;
+
+      // stream_end, complete, status, permission_*, session_created
+      // are control events — not rendered as messages
+      case 'stream_end':
+      case 'complete':
+      case 'status':
+      case 'permission_request':
+      case 'permission_cancelled':
+      case 'session_created':
+        // Skip — these are handled by useChatRealtimeHandlers
+        break;
+
+      // tool_result is handled via attachment to tool_use above
+      case 'tool_result':
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  return converted;
+}
--- a/src/components/chat/hooks/useChatRealtimeHandlers.ts
+++ b/src/components/chat/hooks/useChatRealtimeHandlers.ts
--- a/src/components/chat/hooks/useChatSessionState.ts
+++ b/src/components/chat/hooks/useChatSessionState.ts
--- a/src/components/chat/tools/components/ToolDiffViewer.tsx
+++ b/src/components/chat/tools/components/ToolDiffViewer.tsx
@@ -33,7 +33,12 @@ export const ToolDiffViewer: React.FC<ToolDiffViewerProps> = ({
    : 'bg-gray-100 dark:bg-gray-800 text-gray-500 dark:text-gray-400';

  const diffLines = useMemo(
-    () => createDiff(oldContent, newContent),
+    () => {
+      if (oldContent === undefined || newContent === undefined) {
+        return [];
+      }
+      return createDiff(oldContent, newContent)
+    },
    [createDiff, oldContent, newContent]
  );

--- a/src/components/chat/utils/chatStorage.ts
+++ b/src/components/chat/utils/chatStorage.ts
@@ -5,32 +5,12 @@ export const CLAUDE_SETTINGS_KEY = 'claude-settings';
 export const safeLocalStorage = {
  setItem: (key: string, value: string) => {
    try {
-      if (key.startsWith('chat_messages_') && typeof value === 'string') {
-        try {
-          const parsed = JSON.parse(value);
-          if (Array.isArray(parsed) && parsed.length > 50) {
-            const truncated = parsed.slice(-50);
-            value = JSON.stringify(truncated);
-          }
-        } catch (parseError) {
-          console.warn('Could not parse chat messages for truncation:', parseError);
-        }
-      }
-
      localStorage.setItem(key, value);
    } catch (error: any) {
      if (error?.name === 'QuotaExceededError') {
        console.warn('localStorage quota exceeded, clearing old data');

        const keys = Object.keys(localStorage);
-        const chatKeys = keys.filter((k) => k.startsWith('chat_messages_')).sort();
-
-        if (chatKeys.length > 3) {
-          chatKeys.slice(0, chatKeys.length - 3).forEach((k) => {
-            localStorage.removeItem(k);
-          });
-        }
-
        const draftKeys = keys.filter((k) => k.startsWith('draft_input_'));
        draftKeys.forEach((k) => {
          localStorage.removeItem(k);
@@ -40,17 +20,6 @@ export const safeLocalStorage = {
          localStorage.setItem(key, value);
        } catch (retryError) {
          console.error('Failed to save to localStorage even after cleanup:', retryError);
-          if (key.startsWith('chat_messages_') && typeof value === 'string') {
-            try {
-              const parsed = JSON.parse(value);
-              if (Array.isArray(parsed) && parsed.length > 10) {
-                const minimal = parsed.slice(-10);
-                localStorage.setItem(key, JSON.stringify(minimal));
-              }
-            } catch (finalError) {
-              console.error('Final save attempt failed:', finalError);
-            }
-          }
        }
      } else {
        console.error('localStorage error:', error);
--- a/src/components/chat/utils/messageTransforms.ts
+++ b/src/components/chat/utils/messageTransforms.ts
@@ -1,6 +1,3 @@
-import type { ChatMessage } from '../types/types';
-import { decodeHtmlEntities, unescapeWithMathProtection } from './chatFormatting';
-
 export interface DiffLine {
  type: 'added' | 'removed';
  content: string;
@@ -9,80 +6,6 @@ export interface DiffLine {

 export type DiffCalculator = (oldStr: string, newStr: string) => DiffLine[];

-type CursorBlob = {
-  id?: string;
-  sequence?: number;
-  rowid?: number;
-  content?: any;
-};
-
-const asArray = <T>(value: unknown): T[] => (Array.isArray(value) ? (value as T[]) : []);
-
-const normalizeToolInput = (value: unknown): string => {
-  if (value === null || value === undefined || value === '') {
-    return '';
-  }
-
-  if (typeof value === 'string') {
-    return value;
-  }
-
-  try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    return String(value);
-  }
-};
-
-const CURSOR_INTERNAL_USER_BLOCK_PATTERNS = [
-  /<user_info>[\s\S]*?<\/user_info>/gi,
-  /<agent_skills>[\s\S]*?<\/agent_skills>/gi,
-  /<available_skills>[\s\S]*?<\/available_skills>/gi,
-  /<environment_context>[\s\S]*?<\/environment_context>/gi,
-  /<environment_info>[\s\S]*?<\/environment_info>/gi,
-];
-
-const extractCursorUserQuery = (rawText: string): string => {
-  const userQueryMatches = [...rawText.matchAll(/<user_query>([\s\S]*?)<\/user_query>/gi)];
-  if (userQueryMatches.length === 0) {
-    return '';
-  }
-
-  return userQueryMatches
-    .map((match) => (match[1] || '').trim())
-    .filter(Boolean)
-    .join('\n')
-    .trim();
-};
-
-const sanitizeCursorUserMessageText = (rawText: string): string => {
-  const decodedText = decodeHtmlEntities(rawText || '').trim();
-  if (!decodedText) {
-    return '';
-  }
-
-  // Cursor stores user-visible text inside <user_query> and prepends hidden context blocks
-  // (<user_info>, <agent_skills>, etc). We only render the actual query in chat history.
-  const extractedUserQuery = extractCursorUserQuery(decodedText);
-  if (extractedUserQuery) {
-    return extractedUserQuery;
-  }
-
-  let sanitizedText = decodedText;
-  CURSOR_INTERNAL_USER_BLOCK_PATTERNS.forEach((pattern) => {
-    sanitizedText = sanitizedText.replace(pattern, '');
-  });
-
-  return sanitizedText.trim();
-};
-
-const toAbsolutePath = (projectPath: string, filePath?: string) => {
-  if (!filePath) {
-    return filePath;
-  }
-  return filePath.startsWith('/') ? filePath : `${projectPath}/${filePath}`;
-};
-
 export const calculateDiff = (oldStr: string, newStr: string): DiffLine[] => {
  const oldLines = oldStr.split('\n');
  const newLines = newStr.split('\n');
@@ -162,434 +85,3 @@ export const createCachedDiffCalculator = (): DiffCalculator => {
    return calculated;
  };
 };
-
-export const convertCursorSessionMessages = (blobs: CursorBlob[], projectPath: string): ChatMessage[] => {
-  const converted: ChatMessage[] = [];
-  const toolUseMap: Record<string, ChatMessage> = {};
-
-  for (let blobIdx = 0; blobIdx < blobs.length; blobIdx += 1) {
-    const blob = blobs[blobIdx];
-    const content = blob.content;
-    let text = '';
-    let role: ChatMessage['type'] = 'assistant';
-    let reasoningText: string | null = null;
-
-    try {
-      if (content?.role && content?.content) {
-        if (content.role === 'system') {
-          continue;
-        }
-
-        if (content.role === 'tool') {
-          const toolItems = asArray<any>(content.content);
-          for (const item of toolItems) {
-            if (item?.type !== 'tool-result') {
-              continue;
-            }
-
-            const toolName = item.toolName === 'ApplyPatch' ? 'Edit' : item.toolName || 'Unknown Tool';
-            const toolCallId = item.toolCallId || content.id;
-            const result = item.result || '';
-
-            if (toolCallId && toolUseMap[toolCallId]) {
-              toolUseMap[toolCallId].toolResult = {
-                content: result,
-                isError: false,
-              };
-            } else {
-              converted.push({
-                type: 'assistant',
-                content: '',
-                timestamp: new Date(Date.now() + blobIdx * 1000),
-                blobId: blob.id,
-                sequence: blob.sequence,
-                rowid: blob.rowid,
-                isToolUse: true,
-                toolName,
-                toolId: toolCallId,
-                toolInput: normalizeToolInput(null),
-                toolResult: {
-                  content: result,
-                  isError: false,
-                },
-              });
-            }
-          }
-          continue;
-        }
-
-        role = content.role === 'user' ? 'user' : 'assistant';
-
-        if (Array.isArray(content.content)) {
-          const textParts: string[] = [];
-
-          for (const part of content.content) {
-            if (part?.type === 'text' && part?.text) {
-              textParts.push(decodeHtmlEntities(part.text));
-              continue;
-            }
-
-            if (part?.type === 'reasoning' && part?.text) {
-              reasoningText = decodeHtmlEntities(part.text);
-              continue;
-            }
-
-            if (part?.type === 'tool-call' || part?.type === 'tool_use') {
-              if (textParts.length > 0 || reasoningText) {
-                converted.push({
-                  type: role,
-                  content: textParts.join('\n'),
-                  reasoning: reasoningText ?? undefined,
-                  timestamp: new Date(Date.now() + blobIdx * 1000),
-                  blobId: blob.id,
-                  sequence: blob.sequence,
-                  rowid: blob.rowid,
-                });
-                textParts.length = 0;
-                reasoningText = null;
-              }
-
-              const toolNameRaw = part.toolName || part.name || 'Unknown Tool';
-              const toolName = toolNameRaw === 'ApplyPatch' ? 'Edit' : toolNameRaw;
-              const toolId = part.toolCallId || part.id || `tool_${blobIdx}`;
-              let toolInput = part.args || part.input;
-
-              if (toolName === 'Edit' && part.args) {
-                if (part.args.patch) {
-                  const patchLines = String(part.args.patch).split('\n');
-                  const oldLines: string[] = [];
-                  const newLines: string[] = [];
-                  let inPatch = false;
-
-                  patchLines.forEach((line) => {
-                    if (line.startsWith('@@')) {
-                      inPatch = true;
-                      return;
-                    }
-                    if (!inPatch) {
-                      return;
-                    }
-
-                    if (line.startsWith('-')) {
-                      oldLines.push(line.slice(1));
-                    } else if (line.startsWith('+')) {
-                      newLines.push(line.slice(1));
-                    } else if (line.startsWith(' ')) {
-                      oldLines.push(line.slice(1));
-                      newLines.push(line.slice(1));
-                    }
-                  });
-
-                  toolInput = {
-                    file_path: toAbsolutePath(projectPath, part.args.file_path),
-                    old_string: oldLines.join('\n') || part.args.patch,
-                    new_string: newLines.join('\n') || part.args.patch,
-                  };
-                } else {
-                  toolInput = part.args;
-                }
-              } else if (toolName === 'Read' && part.args) {
-                const filePath = part.args.path || part.args.file_path;
-                toolInput = {
-                  file_path: toAbsolutePath(projectPath, filePath),
-                };
-              } else if (toolName === 'Write' && part.args) {
-                const filePath = part.args.path || part.args.file_path;
-                toolInput = {
-                  file_path: toAbsolutePath(projectPath, filePath),
-                  content: part.args.contents || part.args.content,
-                };
-              }
-
-              const toolMessage: ChatMessage = {
-                type: 'assistant',
-                content: '',
-                timestamp: new Date(Date.now() + blobIdx * 1000),
-                blobId: blob.id,
-                sequence: blob.sequence,
-                rowid: blob.rowid,
-                isToolUse: true,
-                toolName,
-                toolId,
-                toolInput: normalizeToolInput(toolInput),
-                toolResult: null,
-              };
-              converted.push(toolMessage);
-              toolUseMap[toolId] = toolMessage;
-              continue;
-            }
-
-            if (typeof part === 'string') {
-              textParts.push(part);
-            }
-          }
-
-          if (textParts.length > 0) {
-            text = textParts.join('\n');
-            if (reasoningText && !text) {
-              converted.push({
-                type: role,
-                content: '',
-                reasoning: reasoningText,
-                timestamp: new Date(Date.now() + blobIdx * 1000),
-                blobId: blob.id,
-                sequence: blob.sequence,
-                rowid: blob.rowid,
-              });
-              text = '';
-            }
-          } else {
-            text = '';
-          }
-        } else if (typeof content.content === 'string') {
-          text = content.content;
-        }
-      } else if (content?.message?.role && content?.message?.content) {
-        if (content.message.role === 'system') {
-          continue;
-        }
-
-        role = content.message.role === 'user' ? 'user' : 'assistant';
-        if (Array.isArray(content.message.content)) {
-          text = content.message.content
-            .map((part: any) => (typeof part === 'string' ? part : part?.text || ''))
-            .filter(Boolean)
-            .join('\n');
-        } else if (typeof content.message.content === 'string') {
-          text = content.message.content;
-        }
-      }
-    } catch (error) {
-      console.log('Error parsing blob content:', error);
-    }
-
-    if (role === 'user') {
-      text = sanitizeCursorUserMessageText(text);
-    }
-
-    if (text && text.trim()) {
-      const message: ChatMessage = {
-        type: role,
-        content: text,
-        timestamp: new Date(Date.now() + blobIdx * 1000),
-        blobId: blob.id,
-        sequence: blob.sequence,
-        rowid: blob.rowid,
-      };
-      if (reasoningText) {
-        message.reasoning = reasoningText;
-      }
-      converted.push(message);
-    }
-  }
-
-  converted.sort((messageA, messageB) => {
-    if (messageA.sequence !== undefined && messageB.sequence !== undefined) {
-      return Number(messageA.sequence) - Number(messageB.sequence);
-    }
-    if (messageA.rowid !== undefined && messageB.rowid !== undefined) {
-      return Number(messageA.rowid) - Number(messageB.rowid);
-    }
-    return new Date(messageA.timestamp).getTime() - new Date(messageB.timestamp).getTime();
-  });
-
-  return converted;
-};
-
-export const convertSessionMessages = (rawMessages: any[]): ChatMessage[] => {
-  const converted: ChatMessage[] = [];
-  const toolResults = new Map<
-    string,
-    { content: unknown; isError: boolean; timestamp: Date; toolUseResult: unknown; subagentTools?: unknown[] }
-  >();
-
-  rawMessages.forEach((message) => {
-    if (message.message?.role === 'user' && Array.isArray(message.message?.content)) {
-      message.message.content.forEach((part: any) => {
-        if (part.type !== 'tool_result') {
-          return;
-        }
-        toolResults.set(part.tool_use_id, {
-          content: part.content,
-          isError: Boolean(part.is_error),
-          timestamp: new Date(message.timestamp || Date.now()),
-          toolUseResult: message.toolUseResult || null,
-          subagentTools: message.subagentTools,
-        });
-      });
-    }
-  });
-
-  rawMessages.forEach((message) => {
-    if (message.message?.role === 'user' && message.message?.content) {
-      let content = '';
-      if (Array.isArray(message.message.content)) {
-        const textParts: string[] = [];
-        message.message.content.forEach((part: any) => {
-          if (part.type === 'text') {
-            textParts.push(decodeHtmlEntities(part.text));
-          }
-        });
-        content = textParts.join('\n');
-      } else if (typeof message.message.content === 'string') {
-        content = decodeHtmlEntities(message.message.content);
-      } else {
-        content = decodeHtmlEntities(String(message.message.content));
-      }
-
-      const shouldSkip =
-        !content ||
-        content.startsWith('<command-name>') ||
-        content.startsWith('<command-message>') ||
-        content.startsWith('<command-args>') ||
-        content.startsWith('<local-command-stdout>') ||
-        content.startsWith('<system-reminder>') ||
-        content.startsWith('Caveat:') ||
-        content.startsWith('This session is being continued from a previous') ||
-        content.startsWith('[Request interrupted');
-
-      if (!shouldSkip) {
-        // Parse <task-notification> blocks into compact system messages
-        const taskNotifRegex = /<task-notification>\s*<task-id>[^<]*<\/task-id>\s*<output-file>[^<]*<\/output-file>\s*<status>([^<]*)<\/status>\s*<summary>([^<]*)<\/summary>\s*<\/task-notification>/g;
-        const taskNotifMatch = taskNotifRegex.exec(content);
-        if (taskNotifMatch) {
-          const status = taskNotifMatch[1]?.trim() || 'completed';
-          const summary = taskNotifMatch[2]?.trim() || 'Background task finished';
-          converted.push({
-            type: 'assistant',
-            content: summary,
-            timestamp: message.timestamp || new Date().toISOString(),
-            isTaskNotification: true,
-            taskStatus: status,
-          });
-        } else {
-          converted.push({
-            type: 'user',
-            content: unescapeWithMathProtection(content),
-            timestamp: message.timestamp || new Date().toISOString(),
-          });
-        }
-      }
-      return;
-    }
-
-    if (message.type === 'thinking' && message.message?.content) {
-      converted.push({
-        type: 'assistant',
-        content: unescapeWithMathProtection(message.message.content),
-        timestamp: message.timestamp || new Date().toISOString(),
-        isThinking: true,
-      });
-      return;
-    }
-
-    if (message.type === 'tool_use' && message.toolName) {
-      converted.push({
-        type: 'assistant',
-        content: '',
-        timestamp: message.timestamp || new Date().toISOString(),
-        isToolUse: true,
-        toolName: message.toolName,
-        toolInput: normalizeToolInput(message.toolInput),
-        toolCallId: message.toolCallId,
-      });
-      return;
-    }
-
-    if (message.type === 'tool_result') {
-      for (let index = converted.length - 1; index >= 0; index -= 1) {
-        const convertedMessage = converted[index];
-        if (!convertedMessage.isToolUse || convertedMessage.toolResult) {
-          continue;
-        }
-        if (!message.toolCallId || convertedMessage.toolCallId === message.toolCallId) {
-          convertedMessage.toolResult = {
-            content: message.output || '',
-            isError: false,
-          };
-          break;
-        }
-      }
-      return;
-    }
-
-    if (message.message?.role === 'assistant' && message.message?.content) {
-      if (Array.isArray(message.message.content)) {
-        message.message.content.forEach((part: any) => {
-          if (part.type === 'text') {
-            let text = part.text;
-            if (typeof text === 'string') {
-              text = unescapeWithMathProtection(text);
-            }
-            converted.push({
-              type: 'assistant',
-              content: text,
-              timestamp: message.timestamp || new Date().toISOString(),
-            });
-            return;
-          }
-
-          if (part.type === 'tool_use') {
-            const toolResult = toolResults.get(part.id);
-            const isSubagentContainer = part.name === 'Task';
-
-            // Build child tools from server-provided subagentTools data
-            const childTools: import('../types/types').SubagentChildTool[] = [];
-            if (isSubagentContainer && toolResult?.subagentTools && Array.isArray(toolResult.subagentTools)) {
-              for (const tool of toolResult.subagentTools as any[]) {
-                childTools.push({
-                  toolId: tool.toolId,
-                  toolName: tool.toolName,
-                  toolInput: tool.toolInput,
-                  toolResult: tool.toolResult || null,
-                  timestamp: new Date(tool.timestamp || Date.now()),
-                });
-              }
-            }
-
-            converted.push({
-              type: 'assistant',
-              content: '',
-              timestamp: message.timestamp || new Date().toISOString(),
-              isToolUse: true,
-              toolName: part.name,
-              toolInput: normalizeToolInput(part.input),
-              toolId: part.id,
-              toolResult: toolResult
-                ? {
-                    content:
-                      typeof toolResult.content === 'string'
-                        ? toolResult.content
-                        : JSON.stringify(toolResult.content),
-                    isError: toolResult.isError,
-                    toolUseResult: toolResult.toolUseResult,
-                  }
-                : null,
-              toolError: toolResult?.isError || false,
-              toolResultTimestamp: toolResult?.timestamp || new Date(),
-              isSubagentContainer,
-              subagentState: isSubagentContainer
-                ? {
-                    childTools,
-                    currentToolIndex: childTools.length > 0 ? childTools.length - 1 : -1,
-                    isComplete: Boolean(toolResult),
-                  }
-                : undefined,
-            });
-          }
-        });
-        return;
-      }
-
-      if (typeof message.message.content === 'string') {
-        converted.push({
-          type: 'assistant',
-          content: unescapeWithMathProtection(message.message.content),
-          timestamp: message.timestamp || new Date().toISOString(),
-        });
-      }
-    }
-  });
-
-  return converted;
-};
--- a/src/components/chat/view/ChatInterface.tsx
+++ b/src/components/chat/view/ChatInterface.tsx
@@ -3,10 +3,12 @@ import { useTranslation } from 'react-i18next';
 import { useTasksSettings } from '../../../contexts/TasksSettingsContext';
 import { QuickSettingsPanel } from '../../quick-settings-panel';
 import type { ChatInterfaceProps, Provider  } from '../types/types';
+import type { SessionProvider } from '../../../types/app';
 import { useChatProviderState } from '../hooks/useChatProviderState';
 import { useChatSessionState } from '../hooks/useChatSessionState';
 import { useChatRealtimeHandlers } from '../hooks/useChatRealtimeHandlers';
 import { useChatComposerState } from '../hooks/useChatComposerState';
+import { useSessionStore } from '../../../stores/useSessionStore';
 import ChatMessagesPane from './subcomponents/ChatMessagesPane';
 import ChatComposer from './subcomponents/ChatComposer';

@@ -43,8 +45,10 @@ function ChatInterface({
  const { tasksEnabled, isTaskMasterInstalled } = useTasksSettings();
  const { t } = useTranslation('chat');

+  const sessionStore = useSessionStore();
  const streamBufferRef = useRef('');
  const streamTimerRef = useRef<number | null>(null);
+  const accumulatedStreamRef = useRef('');
  const pendingViewSessionRef = useRef<PendingViewSession | null>(null);

  const resetStreamingState = useCallback(() => {
@@ -53,6 +57,7 @@ function ChatInterface({
      streamTimerRef.current = null;
    }
    streamBufferRef.current = '';
+    accumulatedStreamRef.current = '';
  }, []);

  const {
@@ -76,18 +81,17 @@ function ChatInterface({

  const {
    chatMessages,
-    setChatMessages,
+    addMessage,
+    clearMessages,
+    rewindMessages,
    isLoading,
    setIsLoading,
    currentSessionId,
    setCurrentSessionId,
-    sessionMessages,
-    setSessionMessages,
    isLoadingSessionMessages,
    isLoadingMoreMessages,
    hasMoreMessages,
    totalMessages,
-    setIsSystemSessionChange,
    canAbortSession,
    setCanAbortSession,
    isUserScrolledUp,
@@ -109,7 +113,6 @@ function ChatInterface({
    scrollToBottom,
    scrollToBottomAndReset,
    handleScroll,
-    loadSessionMessages,
  } = useChatSessionState({
    selectedProject,
    selectedSession,
@@ -120,6 +123,7 @@ function ChatInterface({
    processingSessions,
    resetStreamingState,
    pendingViewSessionRef,
+    sessionStore,
  });

  const {
@@ -189,8 +193,9 @@ function ChatInterface({
    onShowSettings,
    pendingViewSessionRef,
    scrollToBottom,
-    setChatMessages,
-    setSessionMessages,
+    addMessage,
+    clearMessages,
+    rewindMessages,
    setIsLoading,
    setCanAbortSession,
    setClaudeStatus,
@@ -198,22 +203,19 @@ function ChatInterface({
    setPendingPermissionRequests,
  });

-  // On WebSocket reconnect, re-fetch the current session's messages from JSONL so missed
-  // streaming events (e.g. from long tool calls while iOS had the tab backgrounded) are shown.
-  // Also reset isLoading — if the server restarted or the session died mid-stream, the client
-  // would be stuck in "Processing..." forever without this reset.
+  // On WebSocket reconnect, re-fetch the current session's messages from the server
+  // so missed streaming events are shown. Also reset isLoading.
  const handleWebSocketReconnect = useCallback(async () => {
    if (!selectedProject || !selectedSession) return;
-    const provider = (localStorage.getItem('selected-provider') as any) || 'claude';
-    const messages = await loadSessionMessages(selectedProject.name, selectedSession.id, false, provider);
-    if (messages && messages.length > 0) {
-      setChatMessages(messages);
-    }
-    // Reset loading state — if the session is still active, new WebSocket messages will
-    // set it back to true. If it died, this clears the permanent frozen state.
+    const providerVal = (localStorage.getItem('selected-provider') as SessionProvider) || 'claude';
+    await sessionStore.refreshFromServer(selectedSession.id, {
+      provider: (selectedSession.__provider || providerVal) as SessionProvider,
+      projectName: selectedProject.name,
+      projectPath: selectedProject.fullPath || selectedProject.path || '',
+    });
    setIsLoading(false);
    setCanAbortSession(false);
-  }, [selectedProject, selectedSession, loadSessionMessages, setChatMessages, setIsLoading, setCanAbortSession]);
+  }, [selectedProject, selectedSession, sessionStore, setIsLoading, setCanAbortSession]);

  useChatRealtimeHandlers({
    latestMessage,
@@ -222,22 +224,22 @@ function ChatInterface({
    selectedSession,
    currentSessionId,
    setCurrentSessionId,
-    setChatMessages,
    setIsLoading,
    setCanAbortSession,
    setClaudeStatus,
    setTokenBudget,
-    setIsSystemSessionChange,
    setPendingPermissionRequests,
    pendingViewSessionRef,
    streamBufferRef,
    streamTimerRef,
+    accumulatedStreamRef,
    onSessionInactive,
    onSessionProcessing,
    onSessionNotProcessing,
    onReplaceTemporarySession,
    onNavigateToSession,
    onWebSocketReconnect: handleWebSocketReconnect,
+    sessionStore,
  });

  useEffect(() => {
@@ -319,7 +321,7 @@ function ChatInterface({
          isLoadingMoreMessages={isLoadingMoreMessages}
          hasMoreMessages={hasMoreMessages}
          totalMessages={totalMessages}
-          sessionMessagesCount={sessionMessages.length}
+          sessionMessagesCount={chatMessages.length}
          visibleMessageCount={visibleMessageCount}
          visibleMessages={visibleMessages}
          loadEarlierMessages={loadEarlierMessages}
--- a/src/components/plugins/view/PluginSettingsTab.tsx
+++ b/src/components/plugins/view/PluginSettingsTab.tsx
@@ -6,6 +6,7 @@ import type { Plugin } from '../../../contexts/PluginsContext';
 import PluginIcon from './PluginIcon';

 const STARTER_PLUGIN_URL = 'https://github.com/cloudcli-ai/cloudcli-plugin-starter';
+const TERMINAL_PLUGIN_URL = 'https://github.com/cloudcli-ai/cloudcli-plugin-terminal';

 /* ─── Toggle Switch ─────────────────────────────────────────────────────── */
 function ToggleSwitch({ checked, onChange, ariaLabel }: { checked: boolean; onChange: (v: boolean) => void; ariaLabel: string }) {
@@ -264,6 +265,67 @@ function StarterPluginCard({ onInstall, installing }: { onInstall: () => void; i
  );
 }

+/* ─── Terminal Plugin Card ──────────────────────────────────────────────── */
+function TerminalPluginCard({ onInstall, installing }: { onInstall: () => void; installing: boolean }) {
+  const { t } = useTranslation('settings');
+
+  return (
+    <div className="relative flex overflow-hidden rounded-lg border border-dashed border-border bg-card transition-all duration-200 hover:border-blue-400 dark:hover:border-blue-500">
+      <div className="w-[3px] flex-shrink-0 bg-blue-500/30" />
+      <div className="min-w-0 flex-1 p-4">
+        <div className="flex items-start justify-between gap-3">
+          <div className="flex min-w-0 items-center gap-2.5">
+            <div className="h-5 w-5 flex-shrink-0 text-blue-500">
+              <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="h-5 w-5">
+                <rect x="3" y="3" width="18" height="18" rx="2"/>
+                <path d="M7 8l4 4-4 4"/>
+                <line x1="13" y1="16" x2="17" y2="16"/>
+              </svg>
+            </div>
+            <div className="min-w-0">
+              <div className="flex flex-wrap items-center gap-2">
+                <span className="text-sm font-semibold leading-none text-foreground">
+                  {t('pluginSettings.terminalPlugin.name')}
+                </span>
+                <span className="rounded bg-blue-50 px-1.5 py-0.5 text-[10px] font-medium text-blue-600 dark:bg-blue-950/50 dark:text-blue-400">
+                  {t('pluginSettings.terminalPlugin.badge')}
+                </span>
+                <span className="rounded bg-muted px-1.5 py-0.5 text-[10px] text-muted-foreground">
+                  {t('pluginSettings.tab')}
+                </span>
+              </div>
+              <p className="mt-1 text-sm leading-snug text-muted-foreground">
+                {t('pluginSettings.terminalPlugin.description')}
+              </p>
+              <a
+                href={TERMINAL_PLUGIN_URL}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="mt-1 inline-flex items-center gap-1 text-xs text-muted-foreground/60 transition-colors hover:text-foreground"
+              >
+                <GitBranch className="h-3 w-3" />
+                cloudcli-ai/cloudcli-plugin-terminal
+              </a>
+            </div>
+          </div>
+          <button
+            onClick={onInstall}
+            disabled={installing}
+            className="flex flex-shrink-0 items-center gap-1.5 rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-blue-700 disabled:opacity-50"
+          >
+            {installing ? (
+              <Loader2 className="h-3.5 w-3.5 animate-spin" />
+            ) : (
+              <Download className="h-3.5 w-3.5" />
+            )}
+            {installing ? t('pluginSettings.installing') : t('pluginSettings.terminalPlugin.install')}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
 /* ─── Main Component ────────────────────────────────────────────────────── */
 export default function PluginSettingsTab() {
  const { t } = useTranslation('settings');
@@ -273,6 +335,7 @@ export default function PluginSettingsTab() {
  const [gitUrl, setGitUrl] = useState('');
  const [installing, setInstalling] = useState(false);
  const [installingStarter, setInstallingStarter] = useState(false);
+  const [installingTerminal, setInstallingTerminal] = useState(false);
  const [installError, setInstallError] = useState<string | null>(null);
  const [confirmUninstall, setConfirmUninstall] = useState<string | null>(null);
  const [updatingPlugins, setUpdatingPlugins] = useState<Set<string>>(new Set());
@@ -311,6 +374,16 @@ export default function PluginSettingsTab() {
    setInstallingStarter(false);
  };

+  const handleInstallTerminal = async () => {
+    setInstallingTerminal(true);
+    setInstallError(null);
+    const result = await installPlugin(TERMINAL_PLUGIN_URL);
+    if (!result.success) {
+      setInstallError(result.error || t('pluginSettings.installFailed'));
+    }
+    setInstallingTerminal(false);
+  };
+
  const handleUninstall = async (name: string) => {
    if (confirmUninstall !== name) {
      setConfirmUninstall(name);
@@ -326,6 +399,7 @@ export default function PluginSettingsTab() {
  };

  const hasStarterInstalled = plugins.some((p) => p.name === 'project-stats');
+  const hasTerminalInstalled = plugins.some((p) => p.name === 'web-terminal');

  return (
    <div className="space-y-6">
@@ -382,9 +456,16 @@ export default function PluginSettingsTab() {
        </span>
      </p>

-      {/* Starter plugin suggestion — above the list */}
-      {!loading && !hasStarterInstalled && (
-        <StarterPluginCard onInstall={handleInstallStarter} installing={installingStarter} />
+      {/* Official plugin suggestions — above the list */}
+      {!loading && (!hasStarterInstalled || !hasTerminalInstalled) && (
+        <div className="space-y-2">
+          {!hasStarterInstalled && (
+            <StarterPluginCard onInstall={handleInstallStarter} installing={installingStarter} />
+          )}
+          {!hasTerminalInstalled && (
+            <TerminalPluginCard onInstall={handleInstallTerminal} installing={installingTerminal} />
+          )}
+        </div>
      )}

      {/* Plugin List */}
@@ -423,33 +504,30 @@ export default function PluginSettingsTab() {
        </div>
      )}

-      {/* Build your own */}
-      <div className="flex items-center justify-between gap-4 border-t border-border/50 pt-2">
-        <div className="flex min-w-0 items-center gap-2">
-          <BookOpen className="h-3.5 w-3.5 flex-shrink-0 text-muted-foreground/40" />
-          <span className="text-xs text-muted-foreground/60">
-            {t('pluginSettings.buildYourOwn')}
-          </span>
-        </div>
-        <div className="flex flex-shrink-0 items-center gap-3">
-          <a
-            href={STARTER_PLUGIN_URL}
-            target="_blank"
-            rel="noopener noreferrer"
-            className="inline-flex items-center gap-1 text-xs text-muted-foreground/60 transition-colors hover:text-foreground"
-          >
-            {t('pluginSettings.starter')} <ExternalLink className="h-2.5 w-2.5" />
-          </a>
-          <span className="text-muted-foreground/20">·</span>
-          <a
-            href="https://cloudcli.ai/docs/plugin-overview"
-            target="_blank"
-            rel="noopener noreferrer"
-            className="inline-flex items-center gap-1 text-xs text-muted-foreground/60 transition-colors hover:text-foreground"
-          >
-            {t('pluginSettings.docs')} <ExternalLink className="h-2.5 w-2.5" />
-          </a>
-        </div>
+      {/* Starter plugin */}
+      <div className="flex items-center justify-center gap-3 border-t border-border/50 pt-2">
+        <BookOpen className="h-3.5 w-3.5 flex-shrink-0 text-muted-foreground/40" />
+        <span className="text-xs text-muted-foreground/60">
+          {t('pluginSettings.starterPluginLabel')}
+        </span>
+        <span className="text-muted-foreground/20">·</span>
+        <a
+          href={STARTER_PLUGIN_URL}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="inline-flex items-center gap-1 text-xs text-muted-foreground/60 transition-colors hover:text-foreground"
+        >
+          {t('pluginSettings.starter')} <ExternalLink className="h-2.5 w-2.5" />
+        </a>
+        <span className="text-muted-foreground/20">·</span>
+        <a
+          href="https://cloudcli.ai/docs/plugin-overview"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="inline-flex items-center gap-1 text-xs text-muted-foreground/60 transition-colors hover:text-foreground"
+        >
+          {t('pluginSettings.docs')} <ExternalLink className="h-2.5 w-2.5" />
+        </a>
      </div>
    </div>
  );
--- a/src/components/provider-auth/view/ProviderLoginModal.tsx
+++ b/src/components/provider-auth/view/ProviderLoginModal.tsx
@@ -24,7 +24,7 @@ type ProviderLoginModalProps = {
 const getProviderCommand = ({
  provider,
  customCommand,
-  isAuthenticated,
+  isAuthenticated: _isAuthenticated,
 }: {
  provider: CliProvider;
  customCommand?: string;
@@ -35,10 +35,7 @@ const getProviderCommand = ({
  }

  if (provider === 'claude') {
-    if (isAuthenticated) {
-      return 'claude setup-token --dangerously-skip-permissions';
-    }
-    return 'claude /login --dangerously-skip-permissions';
+    return 'claude --dangerously-skip-permissions /login';
  }

  if (provider === 'cursor') {
--- a/src/components/shell/view/Shell.tsx
+++ b/src/components/shell/view/Shell.tsx
@@ -207,15 +207,23 @@ export default function Shell({

  if (minimal) {
    return (
-      <ShellMinimalView
-        terminalContainerRef={terminalContainerRef}
-        authUrl={authUrl}
-        authUrlVersion={authUrlVersion}
-        initialCommand={initialCommand}
-        isConnected={isConnected}
-        openAuthUrlInBrowser={openAuthUrlInBrowser}
-        copyAuthUrlToClipboard={copyAuthUrlToClipboard}
-      />
+      <>
+        <ShellMinimalView
+          terminalContainerRef={terminalContainerRef}
+          authUrl={authUrl}
+          authUrlVersion={authUrlVersion}
+          initialCommand={initialCommand}
+          isConnected={isConnected}
+          openAuthUrlInBrowser={openAuthUrlInBrowser}
+          copyAuthUrlToClipboard={copyAuthUrlToClipboard}
+        />
+        <TerminalShortcutsPanel
+          wsRef={wsRef}
+          terminalRef={terminalRef}
+          isConnected={isConnected}
+          bottomOffset="bottom-0"
+        />
+      </>
    );
  }

--- a/src/components/shell/view/subcomponents/TerminalShortcutsPanel.tsx
+++ b/src/components/shell/view/subcomponents/TerminalShortcutsPanel.tsx
@@ -1,61 +1,65 @@
-import { type MutableRefObject, useState, useCallback, useEffect, useRef } from 'react';
+import { type MutableRefObject, useCallback, useState } from 'react';
 import {
-  ChevronLeft,
-  ChevronRight,
-  Keyboard,
+  Clipboard,
  ArrowDownToLine,
+  ArrowUp,
+  ArrowDown,
+  ArrowLeft,
+  ArrowRight,
 } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import type { Terminal } from '@xterm/xterm';
 import { sendSocketMessage } from '../../utils/socket';

-const SHORTCUTS = [
-  { id: 'escape', labelKey: 'escape', sequence: '\x1b', hint: 'Esc' },
-  { id: 'tab', labelKey: 'tab', sequence: '\t', hint: 'Tab' },
-  { id: 'shift-tab', labelKey: 'shiftTab', sequence: '\x1b[Z', hint: '\u21e7Tab' },
-  { id: 'arrow-up', labelKey: 'arrowUp', sequence: '\x1b[A', hint: '\u2191' },
-  { id: 'arrow-down', labelKey: 'arrowDown', sequence: '\x1b[B', hint: '\u2193' },
-] as const;
+type Shortcut =
+  | { type: 'key'; id: string; label: string; sequence: string }
+  | { type: 'modifier'; id: string; label: string; modifier: 'ctrl' | 'alt' }
+  | { type: 'arrow'; id: string; sequence: string; icon: 'up' | 'down' | 'left' | 'right' };
+
+const MOBILE_KEYS: Shortcut[] = [
+  { type: 'key', id: 'esc', label: 'Esc', sequence: '\x1b' },
+  { type: 'key', id: 'tab', label: 'Tab', sequence: '\t' },
+  { type: 'key', id: 'shift-tab', label: '\u21e7Tab', sequence: '\x1b[Z' },
+  { type: 'modifier', id: 'ctrl', label: 'CTRL', modifier: 'ctrl' },
+  { type: 'modifier', id: 'alt', label: 'ALT', modifier: 'alt' },
+  { type: 'arrow', id: 'arrow-up', sequence: '\x1b[A', icon: 'up' },
+  { type: 'arrow', id: 'arrow-down', sequence: '\x1b[B', icon: 'down' },
+  { type: 'arrow', id: 'arrow-left', sequence: '\x1b[D', icon: 'left' },
+  { type: 'arrow', id: 'arrow-right', sequence: '\x1b[C', icon: 'right' },
+];
+
+const ARROW_ICONS = {
+  up: ArrowUp,
+  down: ArrowDown,
+  left: ArrowLeft,
+  right: ArrowRight,
+} as const;

 type TerminalShortcutsPanelProps = {
  wsRef: MutableRefObject<WebSocket | null>;
  terminalRef: MutableRefObject<Terminal | null>;
  isConnected: boolean;
+  bottomOffset?: string;
 };

 const preventFocusSteal = (e: React.PointerEvent) => e.preventDefault();

+const KEY_BTN =
+  'shrink-0 rounded-md border border-gray-600 bg-gray-700 px-2.5 py-1.5 text-xs font-medium text-gray-100 transition-colors select-none active:bg-blue-600 active:text-white active:border-blue-600 disabled:cursor-not-allowed disabled:opacity-40';
+const KEY_BTN_ACTIVE =
+  'shrink-0 rounded-md border border-blue-500 bg-blue-600 px-2.5 py-1.5 text-xs font-medium text-white transition-colors select-none disabled:cursor-not-allowed disabled:opacity-40';
+const ICON_BTN =
+  'shrink-0 rounded-md border border-gray-600 bg-gray-700 p-1.5 text-gray-100 transition-colors select-none active:bg-blue-600 active:text-white active:border-blue-600 disabled:cursor-not-allowed disabled:opacity-40';
+
 export default function TerminalShortcutsPanel({
  wsRef,
  terminalRef,
  isConnected,
+  bottomOffset = 'bottom-14',
 }: TerminalShortcutsPanelProps) {
  const { t } = useTranslation('settings');
-  const [isOpen, setIsOpen] = useState(false);
-  const closeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  useEffect(() => {
-    return () => {
-      if (closeTimeoutRef.current) {
-        clearTimeout(closeTimeoutRef.current);
-      }
-    };
-  }, []);
-
-  const handleToggle = useCallback(() => {
-    setIsOpen((prev) => !prev);
-  }, []);
-
-  const handleShortcutAction = useCallback((action: () => void) => {
-    action();
-    if (document.activeElement instanceof HTMLElement) {
-      document.activeElement.blur();
-    }
-    if (closeTimeoutRef.current) {
-      clearTimeout(closeTimeoutRef.current);
-    }
-    closeTimeoutRef.current = setTimeout(() => setIsOpen(false), 50);
-  }, []);
+  const [ctrlActive, setCtrlActive] = useState(false);
+  const [altActive, setAltActive] = useState(false);

  const sendInput = useCallback(
    (data: string) => {
@@ -68,103 +72,120 @@ export default function TerminalShortcutsPanel({
    terminalRef.current?.scrollToBottom();
  }, [terminalRef]);

-  return (
-    <>
-      {/* Pull Tab */}
-      <button
-        type="button"
-        onPointerDown={preventFocusSteal}
-        onClick={handleToggle}
-        className={`fixed ${
-          isOpen ? 'right-64' : 'right-0'
-        } z-50 cursor-pointer rounded-l-md border border-gray-200 bg-white p-2 shadow-lg transition-all duration-150 ease-out hover:bg-gray-100 dark:border-gray-700 dark:bg-gray-800 dark:hover:bg-gray-700`}
-        style={{ top: '50%', transform: 'translateY(-50%)' }}
-        aria-label={
-          isOpen
-            ? t('terminalShortcuts.handle.closePanel')
-            : t('terminalShortcuts.handle.openPanel')
+  const pasteFromClipboard = useCallback(async () => {
+    if (typeof navigator === 'undefined' || !navigator.clipboard?.readText) {
+      return;
+    }
+
+    try {
+      const text = await navigator.clipboard.readText();
+      if (text.length > 0) {
+        sendInput(text);
+      }
+    } catch {
+      // Ignore clipboard permission errors.
+    }
+  }, [sendInput]);
+
+  const handleKeyPress = useCallback(
+    (seq: string) => {
+      let finalSeq = seq;
+      if (ctrlActive && seq.length === 1) {
+        const code = seq.toLowerCase().charCodeAt(0);
+        if (code >= 97 && code <= 122) {
+          finalSeq = String.fromCharCode(code - 96);
        }
-      >
-        {isOpen ? (
-          <ChevronRight className="h-5 w-5 text-gray-600 dark:text-gray-400" />
-        ) : (
-          <ChevronLeft className="h-5 w-5 text-gray-600 dark:text-gray-400" />
-        )}
-      </button>
+        setCtrlActive(false);
+      }
+      if (altActive && seq.length === 1) {
+        finalSeq = '\x1b' + finalSeq;
+        setAltActive(false);
+      }
+      sendInput(finalSeq);
+    },
+    [ctrlActive, altActive, sendInput],
+  );

-      {/* Panel */}
-      <div
-        className={`fixed right-0 top-0 z-40 h-full w-64 transform border-l border-border bg-background shadow-xl transition-transform duration-150 ease-out ${
-          isOpen ? 'translate-x-0' : 'translate-x-full'
-        }`}
-      >
-        <div className="flex h-full flex-col">
-          {/* Header */}
-          <div className="border-b border-gray-200 bg-gray-50 p-4 dark:border-gray-700 dark:bg-gray-900">
-            <h3 className="flex items-center gap-2 text-lg font-semibold text-gray-900 dark:text-white">
-              <Keyboard className="h-5 w-5 text-gray-600 dark:text-gray-400" />
-              {t('terminalShortcuts.title')}
-            </h3>
-          </div>
-
-          {/* Content — conditionally rendered so buttons remount with clean CSS states */}
-          {isOpen && (
-            <div className="flex-1 space-y-6 overflow-y-auto overflow-x-hidden bg-background p-4">
-              {/* Shortcut Keys */}
-              <div className="space-y-2">
-                <h4 className="mb-2 text-xs font-semibold uppercase tracking-wider text-gray-500 dark:text-gray-400">
-                  {t('terminalShortcuts.sectionKeys')}
-                </h4>
-                {SHORTCUTS.map((shortcut) => (
-                  <button
-                    type="button"
-                    key={shortcut.id}
-                    onPointerDown={preventFocusSteal}
-                    onClick={() => handleShortcutAction(() => sendInput(shortcut.sequence))}
-                    disabled={!isConnected}
-                    className="flex w-full items-center justify-between rounded-lg border border-transparent bg-gray-50 p-3 transition-colors hover:border-gray-300 hover:bg-gray-100 disabled:cursor-not-allowed disabled:opacity-40 dark:bg-gray-800 dark:hover:border-gray-600 dark:hover:bg-gray-700"
-                  >
-                    <span className="text-sm text-gray-900 dark:text-white">
-                      {t(`terminalShortcuts.${shortcut.labelKey}`)}
-                    </span>
-                    <kbd className="rounded border border-gray-300 bg-gray-200 px-2 py-0.5 font-mono text-xs text-gray-600 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-300">
-                      {shortcut.hint}
-                    </kbd>
-                  </button>
-                ))}
-              </div>
-
-              {/* Navigation */}
-              <div className="space-y-2">
-                <h4 className="mb-2 text-xs font-semibold uppercase tracking-wider text-gray-500 dark:text-gray-400">
-                  {t('terminalShortcuts.sectionNavigation')}
-                </h4>
-                <button
-                  type="button"
-                  onPointerDown={preventFocusSteal}
-                  onClick={() => handleShortcutAction(scrollToBottom)}
-                  disabled={!isConnected}
-                  className="flex w-full items-center justify-between rounded-lg border border-transparent bg-gray-50 p-3 transition-colors hover:border-gray-300 hover:bg-gray-100 disabled:cursor-not-allowed disabled:opacity-40 dark:bg-gray-800 dark:hover:border-gray-600 dark:hover:bg-gray-700"
-                >
-                  <span className="text-sm text-gray-900 dark:text-white">
-                    {t('terminalShortcuts.scrollDown')}
-                  </span>
-                  <ArrowDownToLine className="h-4 w-4 text-gray-600 dark:text-gray-400" />
-                </button>
-              </div>
-            </div>
-          )}
-        </div>
-      </div>
-
-      {/* Backdrop */}
-      {isOpen && (
-        <div
-          className="fixed inset-0 z-30 bg-background/80 backdrop-blur-sm transition-opacity duration-150 ease-out"
+  return (
+    <div className={`pointer-events-none fixed inset-x-0 ${bottomOffset} z-20 px-2 md:hidden`}>
+      <div className="pointer-events-auto flex items-center gap-1 overflow-x-auto rounded-lg border border-gray-700/80 bg-gray-900/95 px-1.5 py-1.5 shadow-lg backdrop-blur-sm [-webkit-overflow-scrolling:touch] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
+        <button
+          type="button"
          onPointerDown={preventFocusSteal}
-          onClick={handleToggle}
-        />
-      )}
-    </>
+          onClick={() => {
+            void pasteFromClipboard();
+          }}
+          disabled={!isConnected}
+          className={ICON_BTN}
+          title={t('terminalShortcuts.paste', { defaultValue: 'Paste' })}
+          aria-label={t('terminalShortcuts.paste', { defaultValue: 'Paste' })}
+        >
+          <Clipboard className="h-4 w-4" />
+        </button>
+
+        {MOBILE_KEYS.map((key) => {
+          if (key.type === 'modifier') {
+            const isActive = key.modifier === 'ctrl' ? ctrlActive : altActive;
+            const toggle =
+              key.modifier === 'ctrl'
+                ? () => setCtrlActive((v) => !v)
+                : () => setAltActive((v) => !v);
+            return (
+              <button
+                type="button"
+                key={key.id}
+                onPointerDown={preventFocusSteal}
+                onClick={toggle}
+                disabled={!isConnected}
+                className={isActive ? KEY_BTN_ACTIVE : KEY_BTN}
+              >
+                {key.label}
+              </button>
+            );
+          }
+
+          if (key.type === 'arrow') {
+            const Icon = ARROW_ICONS[key.icon];
+            return (
+              <button
+                type="button"
+                key={key.id}
+                onPointerDown={preventFocusSteal}
+                onClick={() => sendInput(key.sequence)}
+                disabled={!isConnected}
+                className={ICON_BTN}
+              >
+                <Icon className="h-4 w-4" />
+              </button>
+            );
+          }
+
+          return (
+            <button
+              type="button"
+              key={key.id}
+              onPointerDown={preventFocusSteal}
+              onClick={() => handleKeyPress(key.sequence)}
+              disabled={!isConnected}
+              className={KEY_BTN}
+            >
+              {key.label}
+            </button>
+          );
+        })}
+
+        <button
+          type="button"
+          onPointerDown={preventFocusSteal}
+          onClick={scrollToBottom}
+          disabled={!isConnected}
+          className={ICON_BTN}
+          title={t('terminalShortcuts.scrollDown')}
+          aria-label={t('terminalShortcuts.scrollDown')}
+        >
+          <ArrowDownToLine className="h-4 w-4" />
+        </button>
+      </div>
+    </div>
  );
 }
--- a/src/i18n/locales/en/settings.json
+++ b/src/i18n/locales/en/settings.json
@@ -476,7 +476,7 @@
    "installFailed": "Installation failed",
    "uninstallFailed": "Uninstall failed",
    "toggleFailed": "Toggle failed",
-    "buildYourOwn": "Build your own plugin",
+    "starterPluginLabel": "Starter Plugin",
    "starter": "Starter",
    "docs": "Docs",
    "starterPlugin": {
@@ -485,6 +485,12 @@
      "description": "File counts, lines of code, file-type breakdown, and recent activity for your project.",
      "install": "Install"
    },
+    "terminalPlugin": {
+      "name": "Terminal",
+      "badge": "official",
+      "description": "Integrated terminal with full shell access directly within the interface.",
+      "install": "Install"
+    },
    "morePlugins": "More",
    "enable": "Enable",
    "disable": "Disable",
--- a/src/stores/useSessionStore.ts
+++ b/src/stores/useSessionStore.ts
@@ -0,0 +1,455 @@
+/**
+ * Session-keyed message store.
+ *
+ * Holds per-session state in a Map keyed by sessionId.
+ * Session switch = change activeSessionId pointer. No clearing. Old data stays.
+ * WebSocket handler = store.appendRealtime(msg.sessionId, msg). One line.
+ * No localStorage for messages. Backend JSONL is the source of truth.
+ */
+
+import { useCallback, useMemo, useRef, useState } from 'react';
+import type { SessionProvider } from '../types/app';
+import { authenticatedFetch } from '../utils/api';
+
+// ─── NormalizedMessage (mirrors server/adapters/types.js) ────────────────────
+
+export type MessageKind =
+  | 'text'
+  | 'tool_use'
+  | 'tool_result'
+  | 'thinking'
+  | 'stream_delta'
+  | 'stream_end'
+  | 'error'
+  | 'complete'
+  | 'status'
+  | 'permission_request'
+  | 'permission_cancelled'
+  | 'session_created'
+  | 'interactive_prompt'
+  | 'task_notification';
+
+export interface NormalizedMessage {
+  id: string;
+  sessionId: string;
+  timestamp: string;
+  provider: SessionProvider;
+  kind: MessageKind;
+
+  // kind-specific fields (flat for simplicity)
+  role?: 'user' | 'assistant';
+  content?: string;
+  images?: string[];
+  toolName?: string;
+  toolInput?: unknown;
+  toolId?: string;
+  toolResult?: { content: string; isError: boolean; toolUseResult?: unknown } | null;
+  isError?: boolean;
+  text?: string;
+  tokens?: number;
+  canInterrupt?: boolean;
+  tokenBudget?: unknown;
+  requestId?: string;
+  input?: unknown;
+  context?: unknown;
+  newSessionId?: string;
+  status?: string;
+  summary?: string;
+  exitCode?: number;
+  actualSessionId?: string;
+  parentToolUseId?: string;
+  subagentTools?: unknown[];
+  isFinal?: boolean;
+  // Cursor-specific ordering
+  sequence?: number;
+  rowid?: number;
+}
+
+// ─── Per-session slot ────────────────────────────────────────────────────────
+
+export type SessionStatus = 'idle' | 'loading' | 'streaming' | 'error';
+
+export interface SessionSlot {
+  serverMessages: NormalizedMessage[];
+  realtimeMessages: NormalizedMessage[];
+  merged: NormalizedMessage[];
+  /** @internal Cache-invalidation refs for computeMerged */
+  _lastServerRef: NormalizedMessage[];
+  _lastRealtimeRef: NormalizedMessage[];
+  status: SessionStatus;
+  fetchedAt: number;
+  total: number;
+  hasMore: boolean;
+  offset: number;
+  tokenUsage: unknown;
+}
+
+const EMPTY: NormalizedMessage[] = [];
+
+function createEmptySlot(): SessionSlot {
+  return {
+    serverMessages: EMPTY,
+    realtimeMessages: EMPTY,
+    merged: EMPTY,
+    _lastServerRef: EMPTY,
+    _lastRealtimeRef: EMPTY,
+    status: 'idle',
+    fetchedAt: 0,
+    total: 0,
+    hasMore: false,
+    offset: 0,
+    tokenUsage: null,
+  };
+}
+
+/**
+ * Compute merged messages: server + realtime, deduped by id.
+ * Server messages take priority (they're the persisted source of truth).
+ * Realtime messages that aren't yet in server stay (in-flight streaming).
+ */
+function computeMerged(server: NormalizedMessage[], realtime: NormalizedMessage[]): NormalizedMessage[] {
+  if (realtime.length === 0) return server;
+  if (server.length === 0) return realtime;
+  const serverIds = new Set(server.map(m => m.id));
+  const extra = realtime.filter(m => !serverIds.has(m.id));
+  if (extra.length === 0) return server;
+  return [...server, ...extra];
+}
+
+/**
+ * Recompute slot.merged only when the input arrays have actually changed
+ * (by reference). Returns true if merged was recomputed.
+ */
+function recomputeMergedIfNeeded(slot: SessionSlot): boolean {
+  if (slot.serverMessages === slot._lastServerRef && slot.realtimeMessages === slot._lastRealtimeRef) {
+    return false;
+  }
+  slot._lastServerRef = slot.serverMessages;
+  slot._lastRealtimeRef = slot.realtimeMessages;
+  slot.merged = computeMerged(slot.serverMessages, slot.realtimeMessages);
+  return true;
+}
+
+// ─── Stale threshold ─────────────────────────────────────────────────────────
+
+const STALE_THRESHOLD_MS = 30_000;
+
+const MAX_REALTIME_MESSAGES = 500;
+
+// ─── Hook ────────────────────────────────────────────────────────────────────
+
+export function useSessionStore() {
+  const storeRef = useRef(new Map<string, SessionSlot>());
+  const activeSessionIdRef = useRef<string | null>(null);
+  // Bump to force re-render — only when the active session's data changes
+  const [, setTick] = useState(0);
+  const notify = useCallback((sessionId: string) => {
+    if (sessionId === activeSessionIdRef.current) {
+      setTick(n => n + 1);
+    }
+  }, []);
+
+  const setActiveSession = useCallback((sessionId: string | null) => {
+    activeSessionIdRef.current = sessionId;
+  }, []);
+
+  const getSlot = useCallback((sessionId: string): SessionSlot => {
+    const store = storeRef.current;
+    if (!store.has(sessionId)) {
+      store.set(sessionId, createEmptySlot());
+    }
+    return store.get(sessionId)!;
+  }, []);
+
+  const has = useCallback((sessionId: string) => storeRef.current.has(sessionId), []);
+
+  /**
+   * Fetch messages from the unified endpoint and populate serverMessages.
+   */
+  const fetchFromServer = useCallback(async (
+    sessionId: string,
+    opts: {
+      provider?: SessionProvider;
+      projectName?: string;
+      projectPath?: string;
+      limit?: number | null;
+      offset?: number;
+    } = {},
+  ) => {
+    const slot = getSlot(sessionId);
+    slot.status = 'loading';
+    notify(sessionId);
+
+    try {
+      const params = new URLSearchParams();
+      if (opts.provider) params.append('provider', opts.provider);
+      if (opts.projectName) params.append('projectName', opts.projectName);
+      if (opts.projectPath) params.append('projectPath', opts.projectPath);
+      if (opts.limit !== null && opts.limit !== undefined) {
+        params.append('limit', String(opts.limit));
+        params.append('offset', String(opts.offset ?? 0));
+      }
+
+      const qs = params.toString();
+      const url = `/api/sessions/${encodeURIComponent(sessionId)}/messages${qs ? `?${qs}` : ''}`;
+      const response = await authenticatedFetch(url);
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      const data = await response.json();
+      const messages: NormalizedMessage[] = data.messages || [];
+
+      slot.serverMessages = messages;
+      slot.total = data.total ?? messages.length;
+      slot.hasMore = Boolean(data.hasMore);
+      slot.offset = (opts.offset ?? 0) + messages.length;
+      slot.fetchedAt = Date.now();
+      slot.status = 'idle';
+      recomputeMergedIfNeeded(slot);
+      if (data.tokenUsage) {
+        slot.tokenUsage = data.tokenUsage;
+      }
+
+      notify(sessionId);
+      return slot;
+    } catch (error) {
+      console.error(`[SessionStore] fetch failed for ${sessionId}:`, error);
+      slot.status = 'error';
+      notify(sessionId);
+      return slot;
+    }
+  }, [getSlot, notify]);
+
+  /**
+   * Load older (paginated) messages and prepend to serverMessages.
+   */
+  const fetchMore = useCallback(async (
+    sessionId: string,
+    opts: {
+      provider?: SessionProvider;
+      projectName?: string;
+      projectPath?: string;
+      limit?: number;
+    } = {},
+  ) => {
+    const slot = getSlot(sessionId);
+    if (!slot.hasMore) return slot;
+
+    const params = new URLSearchParams();
+    if (opts.provider) params.append('provider', opts.provider);
+    if (opts.projectName) params.append('projectName', opts.projectName);
+    if (opts.projectPath) params.append('projectPath', opts.projectPath);
+    const limit = opts.limit ?? 20;
+    params.append('limit', String(limit));
+    params.append('offset', String(slot.offset));
+
+    const qs = params.toString();
+    const url = `/api/sessions/${encodeURIComponent(sessionId)}/messages${qs ? `?${qs}` : ''}`;
+
+    try {
+      const response = await authenticatedFetch(url);
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      const data = await response.json();
+      const olderMessages: NormalizedMessage[] = data.messages || [];
+
+      // Prepend older messages (they're earlier in the conversation)
+      slot.serverMessages = [...olderMessages, ...slot.serverMessages];
+      slot.hasMore = Boolean(data.hasMore);
+      slot.offset = slot.offset + olderMessages.length;
+      recomputeMergedIfNeeded(slot);
+      notify(sessionId);
+      return slot;
+    } catch (error) {
+      console.error(`[SessionStore] fetchMore failed for ${sessionId}:`, error);
+      return slot;
+    }
+  }, [getSlot, notify]);
+
+  /**
+   * Append a realtime (WebSocket) message to the correct session slot.
+   * This works regardless of which session is actively viewed.
+   */
+  const appendRealtime = useCallback((sessionId: string, msg: NormalizedMessage) => {
+    const slot = getSlot(sessionId);
+    let updated = [...slot.realtimeMessages, msg];
+    if (updated.length > MAX_REALTIME_MESSAGES) {
+      updated = updated.slice(-MAX_REALTIME_MESSAGES);
+    }
+    slot.realtimeMessages = updated;
+    recomputeMergedIfNeeded(slot);
+    notify(sessionId);
+  }, [getSlot, notify]);
+
+  /**
+   * Append multiple realtime messages at once (batch).
+   */
+  const appendRealtimeBatch = useCallback((sessionId: string, msgs: NormalizedMessage[]) => {
+    if (msgs.length === 0) return;
+    const slot = getSlot(sessionId);
+    let updated = [...slot.realtimeMessages, ...msgs];
+    if (updated.length > MAX_REALTIME_MESSAGES) {
+      updated = updated.slice(-MAX_REALTIME_MESSAGES);
+    }
+    slot.realtimeMessages = updated;
+    recomputeMergedIfNeeded(slot);
+    notify(sessionId);
+  }, [getSlot, notify]);
+
+  /**
+   * Re-fetch serverMessages from the unified endpoint (e.g., on projects_updated).
+   */
+  const refreshFromServer = useCallback(async (
+    sessionId: string,
+    opts: {
+      provider?: SessionProvider;
+      projectName?: string;
+      projectPath?: string;
+    } = {},
+  ) => {
+    const slot = getSlot(sessionId);
+    try {
+      const params = new URLSearchParams();
+      if (opts.provider) params.append('provider', opts.provider);
+      if (opts.projectName) params.append('projectName', opts.projectName);
+      if (opts.projectPath) params.append('projectPath', opts.projectPath);
+
+      const qs = params.toString();
+      const url = `/api/sessions/${encodeURIComponent(sessionId)}/messages${qs ? `?${qs}` : ''}`;
+      const response = await authenticatedFetch(url);
+
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      const data = await response.json();
+
+      slot.serverMessages = data.messages || [];
+      slot.total = data.total ?? slot.serverMessages.length;
+      slot.hasMore = Boolean(data.hasMore);
+      slot.fetchedAt = Date.now();
+      // drop realtime messages that the server has caught up with to prevent unbounded growth.
+      slot.realtimeMessages = [];
+      recomputeMergedIfNeeded(slot);
+      notify(sessionId);
+    } catch (error) {
+      console.error(`[SessionStore] refresh failed for ${sessionId}:`, error);
+    }
+  }, [getSlot, notify]);
+
+  /**
+   * Update session status.
+   */
+  const setStatus = useCallback((sessionId: string, status: SessionStatus) => {
+    const slot = getSlot(sessionId);
+    slot.status = status;
+    notify(sessionId);
+  }, [getSlot, notify]);
+
+  /**
+   * Check if a session's data is stale (>30s old).
+   */
+  const isStale = useCallback((sessionId: string) => {
+    const slot = storeRef.current.get(sessionId);
+    if (!slot) return true;
+    return Date.now() - slot.fetchedAt > STALE_THRESHOLD_MS;
+  }, []);
+
+  /**
+   * Update or create a streaming message (accumulated text so far).
+   * Uses a well-known ID so subsequent calls replace the same message.
+   */
+  const updateStreaming = useCallback((sessionId: string, accumulatedText: string, msgProvider: SessionProvider) => {
+    const slot = getSlot(sessionId);
+    const streamId = `__streaming_${sessionId}`;
+    const msg: NormalizedMessage = {
+      id: streamId,
+      sessionId,
+      timestamp: new Date().toISOString(),
+      provider: msgProvider,
+      kind: 'stream_delta',
+      content: accumulatedText,
+    };
+    const idx = slot.realtimeMessages.findIndex(m => m.id === streamId);
+    if (idx >= 0) {
+      slot.realtimeMessages = [...slot.realtimeMessages];
+      slot.realtimeMessages[idx] = msg;
+    } else {
+      slot.realtimeMessages = [...slot.realtimeMessages, msg];
+    }
+    recomputeMergedIfNeeded(slot);
+    notify(sessionId);
+  }, [getSlot, notify]);
+
+  /**
+   * Finalize streaming: convert the streaming message to a regular text message.
+   * The well-known streaming ID is replaced with a unique text message ID.
+   */
+  const finalizeStreaming = useCallback((sessionId: string) => {
+    const slot = storeRef.current.get(sessionId);
+    if (!slot) return;
+    const streamId = `__streaming_${sessionId}`;
+    const idx = slot.realtimeMessages.findIndex(m => m.id === streamId);
+    if (idx >= 0) {
+      const stream = slot.realtimeMessages[idx];
+      slot.realtimeMessages = [...slot.realtimeMessages];
+      slot.realtimeMessages[idx] = {
+        ...stream,
+        id: `text_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        kind: 'text',
+        role: 'assistant',
+      };
+      recomputeMergedIfNeeded(slot);
+      notify(sessionId);
+    }
+  }, [notify]);
+
+  /**
+   * Clear realtime messages for a session (e.g., after stream completes and server fetch catches up).
+   */
+  const clearRealtime = useCallback((sessionId: string) => {
+    const slot = storeRef.current.get(sessionId);
+    if (slot) {
+      slot.realtimeMessages = [];
+      recomputeMergedIfNeeded(slot);
+      notify(sessionId);
+    }
+  }, [notify]);
+
+  /**
+   * Get merged messages for a session (for rendering).
+   */
+  const getMessages = useCallback((sessionId: string): NormalizedMessage[] => {
+    return storeRef.current.get(sessionId)?.merged ?? [];
+  }, []);
+
+  /**
+   * Get session slot (for status, pagination info, etc.).
+   */
+  const getSessionSlot = useCallback((sessionId: string): SessionSlot | undefined => {
+    return storeRef.current.get(sessionId);
+  }, []);
+
+  return useMemo(() => ({
+    getSlot,
+    has,
+    fetchFromServer,
+    fetchMore,
+    appendRealtime,
+    appendRealtimeBatch,
+    refreshFromServer,
+    setActiveSession,
+    setStatus,
+    isStale,
+    updateStreaming,
+    finalizeStreaming,
+    clearRealtime,
+    getMessages,
+    getSessionSlot,
+  }), [
+    getSlot, has, fetchFromServer, fetchMore,
+    appendRealtime, appendRealtimeBatch, refreshFromServer,
+    setActiveSession, setStatus, isStale, updateStreaming, finalizeStreaming,
+    clearRealtime, getMessages, getSessionSlot,
+  ]);
+}
+
+export type SessionStore = ReturnType<typeof useSessionStore>;
--- a/src/utils/api.js
+++ b/src/utils/api.js
@@ -54,25 +54,18 @@ export const api = {
  projects: () => authenticatedFetch('/api/projects'),
  sessions: (projectName, limit = 5, offset = 0) =>
    authenticatedFetch(`/api/projects/${projectName}/sessions?limit=${limit}&offset=${offset}`),
-  sessionMessages: (projectName, sessionId, limit = null, offset = 0, provider = 'claude') => {
+  // Unified endpoint — all providers through one URL
+  unifiedSessionMessages: (sessionId, provider = 'claude', { projectName = '', projectPath = '', limit = null, offset = 0 } = {}) => {
    const params = new URLSearchParams();
+    params.append('provider', provider);
+    if (projectName) params.append('projectName', projectName);
+    if (projectPath) params.append('projectPath', projectPath);
    if (limit !== null) {
-      params.append('limit', limit);
-      params.append('offset', offset);
+      params.append('limit', String(limit));
+      params.append('offset', String(offset));
    }
    const queryString = params.toString();
-
-    let url;
-    if (provider === 'codex') {
-      url = `/api/codex/sessions/${sessionId}/messages${queryString ? `?${queryString}` : ''}`;
-    } else if (provider === 'cursor') {
-      url = `/api/cursor/sessions/${sessionId}/messages${queryString ? `?${queryString}` : ''}`;
-    } else if (provider === 'gemini') {
-      url = `/api/gemini/sessions/${sessionId}/messages${queryString ? `?${queryString}` : ''}`;
-    } else {
-      url = `/api/projects/${projectName}/sessions/${sessionId}/messages${queryString ? `?${queryString}` : ''}`;
-    }
-    return authenticatedFetch(url);
+    return authenticatedFetch(`/api/sessions/${encodeURIComponent(sessionId)}/messages${queryString ? `?${queryString}` : ''}`);
  },
  renameProject: (projectName, displayName) =>
    authenticatedFetch(`/api/projects/${projectName}/rename`, {
Author	SHA1	Message	Date
viper151	051a6b1e74	chore(release): v1.27.1	2026-03-29 01:15:38 +00:00
simosmik	f1063fd339	chore: release tokens	2026-03-29 01:13:13 +00:00
simosmik	27cd12432b	chore: relicense to AGPL-3.0-or-later Siteboon AI B.V. contributions relicensed from GPL-3.0 to AGPL-3.0-or-later. Existing community contributions remain under GPL-3.0, combined per GPL-3.0 Section 13. Adds Section 7 additional terms (attribution, origin protection, publicity restriction, trademark).	2026-03-29 00:57:09 +00:00
simosmik	004135ef01	chore: add terminal plugin in the plugins list Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-27 10:38:00 +00:00
xiguatoutou	b54cdf8168	fix: prevent split on undefined（#491） (#563 )	2026-03-23 20:14:15 +03:00
simosmik	42a131389a	chore: add release-it github action	2026-03-22 01:41:21 +00:00
simosmik	ebd1c0db92	chore(release): v1.26.3	2026-03-22 01:10:13 +00:00
simosmik	6d87cc5566	chore(release): v1.26.2	2026-03-21 16:59:38 +00:00
simosmik	17d6ec54af	fix: change SW cache mechanism	2026-03-21 16:49:56 +00:00
simosmik	a41d2c713e	fix: claude auth changes and adding copy on mobile	2026-03-21 16:40:44 +00:00
simosmik	08a6653b38	chore(release): v1.26.0	2026-03-20 15:42:41 +00:00
Simos Mikelatos	a4632dc4ce	feat: unified message architecture with provider adapters and session store (#558 ) - Add provider adapter layer (server/providers/) with registry pattern - Claude, Cursor, Codex, Gemini adapters normalize native formats to NormalizedMessage - Shared types.js defines ProviderAdapter interface and message kinds - Registry enables polymorphic provider lookup - Add unified REST endpoint: GET /api/sessions/:id/messages?provider=... - Replaces four provider-specific message endpoints with one - Delegates to provider adapters via registry - Add frontend session-keyed store (useSessionStore) - Per-session Map with serverMessages/realtimeMessages/merged - Dedup by ID, stale threshold for re-fetch, background session accumulation - No localStorage for messages — backend JSONL is source of truth - Add normalizedToChatMessages converter (useChatMessages) - Converts NormalizedMessage[] to existing ChatMessage[] UI format - Wire unified store into ChatInterface, useChatSessionState, useChatRealtimeHandlers - Session switch uses store cache for instant render - Background WebSocket messages routed to correct session slot	2026-03-19 16:45:06 +03:00