From a1713a5fb76fcda30b77822fbe4ad1c5302338be Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 16:30:01 +0800
Subject: [PATCH 01/25] fix(conversation): wait for explicit run terminal state

---
 CHANGELOG.md                                |  7 ++++
 package-lock.json                           |  4 +-
 package.json                                |  2 +-
 src/__tests__/conversation-client.test.ts   | 44 ++++++++++++++++++++-
 src/__tests__/conversation-protocol.test.ts | 36 +++++++++++++++++
 src/__tests__/hosted-conversation.test.ts   |  4 +-
 src/__tests__/run-engine.test.ts            |  2 +-
 src/core/conversation/client.ts             | 10 ++---
 src/core/conversation/presentation.ts       | 39 +++++++++++++++---
 9 files changed, 130 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8520627..a7d0ea9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.4 - 2026-08-31
+
+- Keep a conversation turn active until an explicit run-level terminal status
+  arrives. Completed user messages, tools, approvals, usage reports, and
+  provider notifications no longer unlock the composer or trigger duplicate
+  submissions while the agent is still running.
+
 ## 0.3.3 - 2026-08-28
 
 ### Headless conversation surface
diff --git a/package-lock.json b/package-lock.json
index f6d88a0..cd749b6 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@kingsoftcloud/ksadk-web",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@kingsoftcloud/ksadk-web",
-      "version": "0.3.3",
+      "version": "0.3.4",
       "license": "Apache-2.0",
       "dependencies": {
         "@ag-ui/client": "0.0.57",
diff --git a/package.json b/package.json
index 8fbb96a..453202a 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@kingsoftcloud/ksadk-web",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "type": "module",
   "scripts": {
     "dev": "vite",
diff --git a/src/__tests__/conversation-client.test.ts b/src/__tests__/conversation-client.test.ts
index a185e6d..21e6731 100644
--- a/src/__tests__/conversation-client.test.ts
+++ b/src/__tests__/conversation-client.test.ts
@@ -165,7 +165,7 @@ describe('HttpConversationClient', () => {
             operation: 'completed',
             lifecycle: 'completed',
             payloadSchemaRef: 'conversation.item.progress/v1',
-            payload: {},
+            payload: { status: 'completed' },
           })),
         ].join(''));
       }
@@ -206,6 +206,48 @@ describe('HttpConversationClient', () => {
     expect(result.presentation.terminalStatus).toBe('completed');
   });
 
+  it('does not treat a completed progress item as a completed run', async () => {
+    const calls: string[] = [];
+    const completedNotification = item('source-notification', '', {
+      itemId: 'notification-1',
+      kind: 'progress',
+      operation: 'completed',
+      lifecycle: 'completed',
+      payloadSchemaRef: 'conversation.item.progress/v1',
+      payload: { message: 'autoApprovalReview' },
+    });
+    const fetcher = vi.fn(async (url: string) => {
+      calls.push(url);
+      if (url.includes('conversation:stream')) {
+        return stream(frame(1, 'item.completed', completedNotification));
+      }
+      return stream(frame(2, 'run.completed', item('source-terminal', '', {
+        itemId: 'run-end',
+        kind: 'progress',
+        operation: 'completed',
+        lifecycle: 'completed',
+        payloadSchemaRef: 'conversation.item.progress/v1',
+        payload: { status: 'completed' },
+      })));
+    });
+    const client = new HttpConversationClient({
+      fetch: fetcher,
+      maxReconnects: 1,
+      sleep: async () => {},
+    });
+
+    const result = await client.streamTurn({
+      bootstrap: { buildId: 'build-1', surface: SURFACE },
+      input: input(),
+    });
+
+    expect(calls).toEqual([
+      '/api/v1/builds/build-1/conversation:stream',
+      '/api/v1/runs/run-1/events?after=1',
+    ]);
+    expect(result.presentation.terminalStatus).toBe('completed');
+  });
+
   it('fails typed when a stream ends before a canonical item supplies run identity', async () => {
     const fetcher = vi.fn(async () => stream(
       'id: 1\nevent: run.created\ndata: {"runId":"not-authoritative-here"}\n\n',
diff --git a/src/__tests__/conversation-protocol.test.ts b/src/__tests__/conversation-protocol.test.ts
index fc97817..5ace386 100644
--- a/src/__tests__/conversation-protocol.test.ts
+++ b/src/__tests__/conversation-protocol.test.ts
@@ -163,6 +163,42 @@ describe('ConversationItem/v1 identity reducer', () => {
 });
 
 describe('ConversationItem/v1 renderer projection', () => {
+  it('only derives run terminal state from an explicit run status', () => {
+    let state = createConversationItemState();
+    state = reduceConversationItem(state, decodedItem({
+      itemId: 'notification-1',
+      sourceEventIds: ['notification-event'],
+      kind: 'progress',
+      operation: 'completed',
+      lifecycle: 'completed',
+      payloadSchemaRef: 'conversation.item.progress/v1',
+      payload: { message: 'autoApprovalReview' },
+    }));
+    expect(projectConversationItems(state).terminalStatus).toBeUndefined();
+
+    state = reduceConversationItem(state, decodedItem({
+      itemId: 'tool-error',
+      sourceEventIds: ['tool-error-event'],
+      kind: 'error',
+      operation: 'completed',
+      lifecycle: 'failed',
+      payloadSchemaRef: 'conversation.item.error/v1',
+      payload: { error: 'one tool failed' },
+    }));
+    expect(projectConversationItems(state).terminalStatus).toBeUndefined();
+
+    state = reduceConversationItem(state, decodedItem({
+      itemId: 'run-end',
+      sourceEventIds: ['run-end-event'],
+      kind: 'progress',
+      operation: 'completed',
+      lifecycle: 'completed',
+      payloadSchemaRef: 'conversation.item.progress/v1',
+      payload: { status: 'completed' },
+    }));
+    expect(projectConversationItems(state).terminalStatus).toBe('completed');
+  });
+
   it('keeps stream order and enriches a tool call with a separate result item', () => {
     let state = createConversationItemState();
     state = reduceConversationItem(state, decodedItem({
diff --git a/src/__tests__/hosted-conversation.test.ts b/src/__tests__/hosted-conversation.test.ts
index d26d9f1..6e4a22b 100644
--- a/src/__tests__/hosted-conversation.test.ts
+++ b/src/__tests__/hosted-conversation.test.ts
@@ -153,7 +153,7 @@ describe('Hosted UI canonical ConversationItem projection', () => {
             'event-9',
             'progress',
             'conversation.item.progress/v1',
-            {},
+            { status: 'completed' },
             { operation: 'completed', lifecycle: 'completed' },
           )),
         ].join(''));
@@ -249,7 +249,7 @@ describe('Hosted UI canonical ConversationItem projection', () => {
           'terminal-event-readonly',
           'progress',
           'conversation.item.progress/v1',
-          {},
+          { status: 'completed' },
           { operation: 'completed', lifecycle: 'completed' },
         )),
       ].join(''))),
diff --git a/src/__tests__/run-engine.test.ts b/src/__tests__/run-engine.test.ts
index a4b99a6..d4b96ed 100644
--- a/src/__tests__/run-engine.test.ts
+++ b/src/__tests__/run-engine.test.ts
@@ -143,7 +143,7 @@ function canonicalResult(): ConversationStreamResult {
       lifecycle: 'completed',
       visibility: 'public',
       payloadSchemaRef: 'conversation.item.progress/v1',
-      payload: {},
+      payload: { status: 'completed' },
       nativeRef: {},
     },
   ];
diff --git a/src/core/conversation/client.ts b/src/core/conversation/client.ts
index cc7933f..6004a64 100644
--- a/src/core/conversation/client.ts
+++ b/src/core/conversation/client.ts
@@ -4,7 +4,10 @@ import {
   preflightConversationInput,
 } from './contracts.js';
 import { ConversationClientError } from './errors.js';
-import { projectConversationItems } from './presentation.js';
+import {
+  conversationTerminalStatus,
+  projectConversationItems,
+} from './presentation.js';
 import { ConversationItemReducer } from './reducer.js';
 import type {
   ConversationClientOptions,
@@ -227,10 +230,7 @@ async function consumeEventStream(
 }
 
 function terminal(result: ConversationStreamResult): boolean {
-  return result.state.items.some((item) => (
-    (item.kind === 'progress' || item.kind === 'error')
-    && (item.lifecycle === 'completed' || item.lifecycle === 'failed')
-  ));
+  return result.state.items.some((item) => conversationTerminalStatus(item) !== undefined);
 }
 
 /**
diff --git a/src/core/conversation/presentation.ts b/src/core/conversation/presentation.ts
index 5580c73..1d44bcc 100644
--- a/src/core/conversation/presentation.ts
+++ b/src/core/conversation/presentation.ts
@@ -20,10 +20,39 @@ const SUPPORTED_SCHEMAS: Partial<Record<ConversationItemKind, string>> = {
   error: 'conversation.item.error/v1',
 };
 
-function terminal(item: ConversationItem): boolean {
+function itemLifecycleTerminal(item: ConversationItem): boolean {
   return item.lifecycle === 'completed' || item.lifecycle === 'failed';
 }
 
+const FAILED_RUN_STATUSES = new Set([
+  'aborted',
+  'canceled',
+  'cancelled',
+  'failed',
+  'incomplete',
+  'interrupted',
+]);
+
+/**
+ * Return a run-level terminal state only for an explicit run status.
+ *
+ * Item lifecycle is scoped to one item. A completed user message, tool call,
+ * approval, usage report, or provider notification must never unlock the
+ * composer while the containing run is still active.
+ */
+export function conversationTerminalStatus(
+  item: ConversationItem,
+): 'completed' | 'failed' | undefined {
+  if ((item.kind !== 'progress' && item.kind !== 'error')
+    || !itemLifecycleTerminal(item)) return undefined;
+  const status = typeof item.payload.status === 'string'
+    ? item.payload.status.toLowerCase()
+    : '';
+  if (status === 'completed') return 'completed';
+  if (FAILED_RUN_STATUSES.has(status)) return 'failed';
+  return undefined;
+}
+
 function schemaSupported(item: ConversationItem): boolean {
   const expected = SUPPORTED_SCHEMAS[item.kind];
   return expected === undefined || expected === item.payloadSchemaRef;
@@ -93,7 +122,7 @@ function mergeTimelineItem(
   previous: ConversationItem,
   incoming: ConversationItem,
 ): ConversationItem {
-  const preserveTerminal = terminal(previous) && !terminal(incoming);
+  const preserveTerminal = itemLifecycleTerminal(previous) && !itemLifecycleTerminal(incoming);
   return {
     ...previous,
     ...incoming,
@@ -160,7 +189,7 @@ export function projectConversationItems(
   ];
   const failures = supported.filter((item) => item.kind === 'error');
   const terminalItem = [...supported].reverse().find((item) => (
-    (item.kind === 'progress' || item.kind === 'error') && terminal(item)
+    conversationTerminalStatus(item) !== undefined
   ));
 
   return {
@@ -197,8 +226,6 @@ export function projectConversationItems(
       })),
     ],
     runId: visible.at(-1)?.runId || '',
-    terminalStatus: terminalItem
-      ? terminalItem.lifecycle === 'failed' ? 'failed' : 'completed'
-      : undefined,
+    terminalStatus: terminalItem ? conversationTerminalStatus(terminalItem) : undefined,
   };
 }

From b13906cfabbe48a205efd52cc9d99b0967f0f8f5 Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 16:30:02 +0800
Subject: [PATCH 02/25] chore(release): attest ksadk-web 0.3.4 source

---
 RELEASE_PROVENANCE.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index bdcdf05..cfbfa80 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
-  "version": "0.3.3",
-  "source_commit": "37eb8dd6ae8c44ea4622d39f8c7ae9b13916a793",
+  "version": "0.3.4",
+  "source_commit": "a1713a5fb76fcda30b77822fbe4ad1c5302338be",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From 79c5ffc66609aae39bcdc5c1c59e07a36601b71d Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 16:32:34 +0800
Subject: [PATCH 03/25] test(conversation): emit explicit terminal status

---
 e2e/fixtures/canonical-conversation-server.mjs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/e2e/fixtures/canonical-conversation-server.mjs b/e2e/fixtures/canonical-conversation-server.mjs
index c262c48..b434317 100644
--- a/e2e/fixtures/canonical-conversation-server.mjs
+++ b/e2e/fixtures/canonical-conversation-server.mjs
@@ -359,6 +359,7 @@ async function streamFirstReconnect(response, requestUrl, request) {
         sourceEventId: 'event-terminal-1',
         kind: 'progress',
         schema: 'conversation.item.progress/v1',
+        payload: { status: 'completed' },
         operation: 'completed',
         lifecycle: 'completed',
       }));
@@ -403,6 +404,7 @@ async function streamSecondTurn(response) {
     sourceEventId: 'event-terminal-2',
     kind: 'progress',
     schema: 'conversation.item.progress/v1',
+    payload: { status: 'completed' },
     operation: 'completed',
     lifecycle: 'completed',
   }));

From 7f7e185546464367dae0d9ba7baa473276849a9c Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 16:32:34 +0800
Subject: [PATCH 04/25] chore(release): refresh ksadk-web 0.3.4 provenance

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index cfbfa80..6182cd3 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "a1713a5fb76fcda30b77822fbe4ad1c5302338be",
+  "source_commit": "79c5ffc66609aae39bcdc5c1c59e07a36601b71d",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From 207fc6468a7ae4a904ba782f28d6c2d80def866c Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 17:22:40 +0800
Subject: [PATCH 05/25] feat(web): publish interactive demo and thinking
 shimmer

---
 .github/workflows/pages.yml                  |   4 +-
 .github/workflows/publish-npm.yml            |   2 +-
 .gitignore                                   |   1 +
 CHANGELOG.md                                 |   7 +
 e2e/demo.spec.ts                             |  22 ++
 package.json                                 |   4 +-
 playwright.demo.config.mjs                   |  20 ++
 scripts/release-preflight.mjs                |   1 +
 src/__tests__/demo-page-contract.test.ts     |  37 +++
 src/components/chat/ProcessingBlocksView.tsx |  15 +-
 src/demo/DemoWorkbench.tsx                   | 247 +++++++++++++++++++
 src/index.css                                |  36 +++
 src/main.tsx                                 |   3 +-
 tests/package-contract.test.mjs              |   5 +-
 14 files changed, 390 insertions(+), 14 deletions(-)
 create mode 100644 e2e/demo.spec.ts
 create mode 100644 playwright.demo.config.mjs
 create mode 100644 src/__tests__/demo-page-contract.test.ts
 create mode 100644 src/demo/DemoWorkbench.tsx

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index e5765df..f3a9546 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -25,11 +25,11 @@ jobs:
 
       - run: npm ci
       - run: npm test
-      - run: npm run build:ksadk
+      - run: npm run build:demo
 
       - uses: actions/upload-pages-artifact@v3
         with:
-          path: dist-ksadk
+          path: dist-demo
 
   deploy:
     environment:
diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml
index d13fe6b..ccd6eeb 100644
--- a/.github/workflows/publish-npm.yml
+++ b/.github/workflows/publish-npm.yml
@@ -55,7 +55,7 @@ jobs:
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: dist-ksadk
+          path: dist-demo
 
   deploy-pages:
     environment:
diff --git a/.gitignore b/.gitignore
index 38f67ff..6135b48 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,7 @@ node_modules/
 dist/
 dist-hosted/
 dist-ksadk/
+dist-demo/
 dist-lib/
 coverage/
 output/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7d0ea9..aa7415a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,13 @@
   arrives. Completed user messages, tools, approvals, usage reports, and
   provider notifications no longer unlock the composer or trigger duplicate
   submissions while the agent is still running.
+- Make active reasoning visibly animated with a motion-safe text shimmer,
+  matching WeWork's low-noise thinking treatment while preserving the compact,
+  collapsible completed state.
+- Publish a dedicated interactive GitHub Pages demo that exercises the shared
+  reasoning, tool, Markdown, and composer components entirely in the browser.
+  It is explicitly labelled as local sample data instead of attempting to
+  connect to a nonexistent Agent backend.
 
 ## 0.3.3 - 2026-08-28
 
diff --git a/e2e/demo.spec.ts b/e2e/demo.spec.ts
new file mode 100644
index 0000000..1e28163
--- /dev/null
+++ b/e2e/demo.spec.ts
@@ -0,0 +1,22 @@
+import { expect, test } from '@playwright/test';
+
+test('public demo visibly streams reasoning, a tool, and Markdown without a backend', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page.getByRole('heading', { name: 'KsADK Web 示例 Agent' })).toBeVisible();
+  await expect(page.getByText('本地交互演示', { exact: true })).toBeVisible();
+  await expect(page.getByText(/不会连接或冒充真实 Agent/)).toBeVisible();
+
+  const composer = page.getByRole('textbox', { name: '演示消息' });
+  const send = page.getByRole('button', { name: '发送演示消息' });
+  await composer.fill('验证公开演示');
+  await send.click();
+
+  await expect(page.getByTestId('thinking-indicator')).toHaveText('正在思考');
+  await expect(page.getByTestId('thinking-indicator')).toHaveClass(/waiting-thinking-text/);
+  await expect(page.getByRole('button', { name: '发送演示消息' })).toBeDisabled();
+  await expect(page.getByRole('button', { name: /正在运行 demo\.echo_context/ })).toBeVisible();
+  await expect(page.getByRole('button', { name: /已完成 demo\.echo_context/ })).toBeVisible();
+  await expect(page.getByText('已收到：“验证公开演示”。')).toBeVisible();
+  await expect(page.getByText(/组件会消费同一套会话、思考、工具、审批与 A2UI 协议/)).toBeVisible();
+});
diff --git a/package.json b/package.json
index 453202a..51448e7 100644
--- a/package.json
+++ b/package.json
@@ -6,8 +6,9 @@
     "dev": "vite",
     "build": "npm run build:ksadk",
     "build:hosted": "VITE_BASE_PATH=/chat/ vite build --outDir dist-hosted",
+    "build:demo": "VITE_DEMO_MODE=1 VITE_BASE_PATH=./ vite build --outDir dist-demo",
     "build:lib": "vite build --config vite.lib.config.ts && tsc -p tsconfig.lib.json",
-    "build:all": "npm run build:ksadk && npm run build:hosted && npm run build:lib",
+    "build:all": "npm run build:ksadk && npm run build:hosted && npm run build:demo && npm run build:lib",
     "prepack": "npm run build:lib && npm run build:ksadk",
     "lint": "eslint .",
     "preview": "vite preview",
@@ -16,6 +17,7 @@
     "test:watch": "vitest src",
     "test:e2e:interaction": "playwright test --config playwright.interaction.config.mjs",
     "test:e2e:conversation": "playwright test --config playwright.canonical-conversation.config.mjs",
+    "test:e2e:demo": "playwright test --config playwright.demo.config.mjs",
     "test:e2e:agui": "playwright test --config playwright.agui.config.mjs",
     "test:e2e:reconnect": "playwright test --config playwright.reconnect.config.mjs",
     "build:ksadk": "VITE_BASE_PATH=./ vite build --outDir dist-ksadk",
diff --git a/playwright.demo.config.mjs b/playwright.demo.config.mjs
new file mode 100644
index 0000000..b26f91d
--- /dev/null
+++ b/playwright.demo.config.mjs
@@ -0,0 +1,20 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  testMatch: 'demo.spec.ts',
+  workers: 1,
+  timeout: 20_000,
+  expect: { timeout: 10_000 },
+  use: {
+    baseURL: 'http://127.0.0.1:4178',
+    viewport: { width: 1280, height: 900 },
+    screenshot: 'only-on-failure',
+    trace: 'retain-on-failure',
+  },
+  webServer: {
+    command: 'VITE_DEMO_MODE=1 npm run dev -- --host 127.0.0.1 --port 4178 --strictPort',
+    url: 'http://127.0.0.1:4178',
+    reuseExistingServer: false,
+  },
+});
diff --git a/scripts/release-preflight.mjs b/scripts/release-preflight.mjs
index a0dbb62..69c6aee 100644
--- a/scripts/release-preflight.mjs
+++ b/scripts/release-preflight.mjs
@@ -15,6 +15,7 @@ export const RELEASE_COMMANDS = Object.freeze([
   ['npm', ['run', 'lint']],
   ['npm', ['run', 'build:all']],
   ['npm', ['run', 'test:e2e:conversation']],
+  ['npm', ['run', 'test:e2e:demo']],
 ]);
 
 function run(command, args, options = {}) {
diff --git a/src/__tests__/demo-page-contract.test.ts b/src/__tests__/demo-page-contract.test.ts
new file mode 100644
index 0000000..2d7a89f
--- /dev/null
+++ b/src/__tests__/demo-page-contract.test.ts
@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+describe('public demo page contract', () => {
+  it('builds a dedicated interactive demo instead of bootstrapping a missing Agent', () => {
+    const main = readFileSync(resolve(repoRoot, 'src/main.tsx'), 'utf8');
+    const demo = readFileSync(resolve(repoRoot, 'src/demo/DemoWorkbench.tsx'), 'utf8');
+    const pages = readFileSync(resolve(repoRoot, '.github/workflows/pages.yml'), 'utf8');
+
+    expect(main).toContain("import.meta.env.VITE_DEMO_MODE === '1'");
+    expect(demo).toContain('本地交互演示');
+    expect(demo).toContain('不会连接或冒充真实 Agent');
+    expect(demo).toContain('setMessages');
+    expect(demo).toContain('status: \'streaming\'');
+    expect(pages).toContain('npm run build:demo');
+    expect(pages).toContain('path: dist-demo');
+  });
+
+  it('uses the WeWork-style text shimmer while reasoning is streaming', () => {
+    const source = readFileSync(
+      resolve(repoRoot, 'src/components/chat/ProcessingBlocksView.tsx'),
+      'utf8',
+    );
+
+    const styles = readFileSync(resolve(repoRoot, 'src/index.css'), 'utf8');
+    expect(source).toContain("generating && 'waiting-thinking-text'");
+    expect(source).toContain("data-testid={generating ? 'thinking-indicator'");
+    expect(source).toContain("generating ? '正在思考' : '已思考'");
+    expect(styles).toContain('@keyframes waiting-thinking-text');
+    expect(styles).toContain('animation: waiting-thinking-text 1.6s linear infinite');
+    expect(styles).toContain('@media (prefers-reduced-motion: reduce)');
+  });
+});
diff --git a/src/components/chat/ProcessingBlocksView.tsx b/src/components/chat/ProcessingBlocksView.tsx
index 765811d..124aea2 100644
--- a/src/components/chat/ProcessingBlocksView.tsx
+++ b/src/components/chat/ProcessingBlocksView.tsx
@@ -80,13 +80,14 @@ function ThinkingRow({ block }: { block: ThinkingBlock }) {
         onClick={() => setOpen((value) => !value)}
         className="flex w-full items-center gap-1.5 rounded px-1 py-1 text-left text-[13px] leading-5 text-slate-400 transition-colors hover:bg-slate-100/70 hover:text-slate-500 dark:text-slate-500 dark:hover:bg-slate-800/40 dark:hover:text-slate-400"
       >
-        <Sparkles
-          className={cn(
-            'h-3.5 w-3.5 shrink-0',
-            generating && 'animate-pulse motion-reduce:animate-none',
-          )}
-        />
-        <span className="min-w-0 truncate">{generating ? '思考中' : '已思考'}</span>
+        {!generating && <Sparkles className="h-3.5 w-3.5 shrink-0" />}
+        <span
+          className={cn('min-w-0 truncate', generating && 'waiting-thinking-text')}
+          data-testid={generating ? 'thinking-indicator' : undefined}
+          role={generating ? 'status' : undefined}
+        >
+          {generating ? '正在思考' : '已思考'}
+        </span>
         {!generating && (
           <>
             <span className="text-slate-300 dark:text-slate-600">·</span>
diff --git a/src/demo/DemoWorkbench.tsx b/src/demo/DemoWorkbench.tsx
new file mode 100644
index 0000000..6a1d90e
--- /dev/null
+++ b/src/demo/DemoWorkbench.tsx
@@ -0,0 +1,247 @@
+import { useEffect, useRef, useState, type FormEvent, type KeyboardEvent } from 'react';
+import {
+  Bot,
+  CheckCircle2,
+  Code2,
+  LoaderCircle,
+  Plus,
+  Send,
+  Sparkles,
+  UserRound,
+} from 'lucide-react';
+
+import { MessageMarkdown } from '../components/MessageMarkdown';
+import { ProcessingBlocksView } from '../components/chat/ProcessingBlocksView';
+import type { Message } from '../components/chat/types';
+
+const initialMessages: Message[] = [
+  {
+    id: 'welcome',
+    role: 'model',
+    content: '',
+    timestamp: Date.now(),
+    blocks: [
+      {
+        id: 'welcome-thinking',
+        type: 'thinking',
+        content: '确认这是不依赖后端的公开演示，并准备展示统一事件渲染。',
+        status: 'done',
+      },
+      {
+        id: 'welcome-tool',
+        type: 'tool',
+        toolName: 'demo.inspect_capabilities',
+        args: '{"surface":"chat"}',
+        output: '{"streaming":true,"reasoning":true,"tools":true}',
+        status: 'completed',
+      },
+      {
+        id: 'welcome-text',
+        type: 'text',
+        content: '这是 **ksadk-web 交互演示**。你可以发送一条消息，观察思考、工具和正文按同一事件时间线逐步出现。',
+        status: 'done',
+      },
+    ],
+  },
+];
+
+export function DemoWorkbench() {
+  const [messages, setMessages] = useState<Message[]>(initialMessages);
+  const [input, setInput] = useState('');
+  const [running, setRunning] = useState(false);
+  const timers = useRef<number[]>([]);
+
+  useEffect(() => () => {
+    timers.current.forEach((timer) => window.clearTimeout(timer));
+  }, []);
+
+  const schedule = (callback: () => void, delay: number) => {
+    timers.current.push(window.setTimeout(callback, delay));
+  };
+
+  const updateResponse = (responseId: string, update: (message: Message) => Message) => {
+    setMessages((current) => current.map((message) => (
+      message.id === responseId ? update(message) : message
+    )));
+  };
+
+  const submit = (event: FormEvent) => {
+    event.preventDefault();
+    const text = input.trim();
+    if (!text || running) return;
+    const stamp = Date.now();
+    const responseId = `demo-response-${stamp}`;
+    setInput('');
+    setRunning(true);
+    setMessages((current) => [
+      ...current,
+      { id: `demo-user-${stamp}`, role: 'user', content: text, timestamp: stamp },
+      {
+        id: responseId,
+        role: 'model',
+        content: '',
+        timestamp: stamp + 1,
+        blocks: [{
+          id: `${responseId}-thinking`,
+          type: 'thinking',
+          content: '正在理解你的请求',
+          status: 'streaming',
+        }],
+      },
+    ]);
+
+    schedule(() => updateResponse(responseId, (message) => ({
+      ...message,
+      blocks: [{
+        id: `${responseId}-thinking`,
+        type: 'thinking',
+        content: '正在理解你的请求，并选择适合的演示工具。',
+        status: 'streaming',
+      }],
+    })), 900);
+    schedule(() => updateResponse(responseId, (message) => ({
+      ...message,
+      blocks: [
+        {
+          id: `${responseId}-thinking`,
+          type: 'thinking',
+          content: '已确认输入内容，接下来执行一个只读示例工具。',
+          status: 'done',
+        },
+        {
+          id: `${responseId}-tool`,
+          type: 'tool',
+          toolName: 'demo.echo_context',
+          args: JSON.stringify({ input: text }, null, 2),
+          status: 'running',
+        },
+      ],
+      tools: {
+        'demo.echo_context': {
+          name: 'demo.echo_context',
+          args: JSON.stringify({ input: text }, null, 2),
+          status: 'running',
+        },
+      },
+    })), 4000);
+    schedule(() => updateResponse(responseId, (message) => ({
+      ...message,
+      blocks: [
+        ...(message.blocks ?? []).map((block) => (
+          block.type === 'tool' ? { ...block, output: '{"ok":true}', status: 'completed' as const } : block
+        )),
+        {
+          id: `${responseId}-text`,
+          type: 'text',
+          content: `已收到：“${text}”。\n\n这个页面展示的是本地可交互事件流；接入真实 Agent 时，组件会消费同一套会话、思考、工具、审批与 A2UI 协议。`,
+          status: 'done',
+        },
+      ],
+      tools: {
+        'demo.echo_context': {
+          name: 'demo.echo_context',
+          args: JSON.stringify({ input: text }, null, 2),
+          output: '{"ok":true}',
+          status: 'completed',
+        },
+      },
+    })), 6500);
+    schedule(() => setRunning(false), 6700);
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault();
+      event.currentTarget.form?.requestSubmit();
+    }
+  };
+
+  return (
+    <div className="flex min-h-screen bg-slate-50 font-sans text-slate-800">
+      <aside className="hidden w-72 shrink-0 border-r border-slate-200 bg-white lg:flex lg:flex-col">
+        <div className="border-b border-slate-100 px-5 py-5">
+          <div className="flex items-center gap-2.5 font-semibold">
+            <span className="flex h-8 w-8 items-center justify-center rounded-xl bg-blue-600 text-white">K</span>
+            ksadk-web
+          </div>
+          <p className="mt-2 text-xs leading-5 text-slate-500">统一 Agent 会话组件</p>
+        </div>
+        <div className="p-3">
+          <button className="w-full rounded-xl bg-blue-50 px-3 py-2.5 text-left text-sm font-medium text-blue-700">
+            交互能力演示
+          </button>
+        </div>
+        <div className="mt-auto border-t border-slate-100 p-4 text-xs leading-5 text-slate-500">
+          <a className="flex items-center gap-2 hover:text-slate-800" href="https://github.com/kingsoftcloud/ksadk-web">
+            <Code2 className="h-4 w-4" /> 查看源码与接入文档
+          </a>
+        </div>
+      </aside>
+
+      <main className="flex min-w-0 flex-1 flex-col bg-white">
+        <header className="flex h-16 items-center justify-between border-b border-slate-100 px-5 sm:px-8">
+          <div className="flex items-center gap-3">
+            <span className="flex h-9 w-9 items-center justify-center rounded-xl bg-slate-100 text-slate-600"><Bot className="h-4 w-4" /></span>
+            <div>
+              <h1 className="text-sm font-semibold">KsADK Web 示例 Agent</h1>
+              <p className="text-xs text-slate-500">思考 · 工具 · Markdown · 会话状态</p>
+            </div>
+          </div>
+          <span className="rounded-full border border-amber-200 bg-amber-50 px-3 py-1 text-xs text-amber-700">本地交互演示</span>
+        </header>
+
+        <div className="flex-1 overflow-y-auto px-5 py-8 sm:px-8">
+          <div className="mx-auto max-w-3xl space-y-6">
+            <div className="rounded-2xl border border-blue-100 bg-blue-50/60 px-4 py-3 text-sm leading-6 text-blue-900">
+              <div className="flex items-center gap-2 font-medium"><Sparkles className="h-4 w-4" /> 无需后端即可体验渲染</div>
+              <p className="mt-1 text-xs text-blue-700/80">这是公开站点的示例数据，不会连接或冒充真实 Agent。生产接入请使用下方源码与文档。</p>
+            </div>
+
+            {messages.map((message, index) => message.role === 'user' ? (
+              <div key={message.id} className="flex justify-end">
+                <div className="max-w-[80%] rounded-2xl rounded-br-md bg-slate-100 px-4 py-3 text-sm leading-6">
+                  <div className="mb-1 flex items-center justify-end gap-1.5 text-[11px] text-slate-500"><UserRound className="h-3 w-3" /> 你</div>
+                  <MessageMarkdown content={message.content} />
+                </div>
+              </div>
+            ) : (
+              <div key={message.id} className="rounded-2xl border border-slate-100 bg-white px-4 py-4 shadow-sm shadow-slate-900/5">
+                <div className="mb-2 flex items-center gap-2 text-xs font-medium text-slate-600"><Bot className="h-3.5 w-3.5" /> 示例 Agent</div>
+                <ProcessingBlocksView message={message} isStreaming={running && index === messages.length - 1} />
+              </div>
+            ))}
+          </div>
+        </div>
+
+        <div className="border-t border-slate-100 bg-white/95 px-4 py-4 backdrop-blur sm:px-8">
+          <form onSubmit={submit} className="mx-auto max-w-3xl rounded-[24px] border border-slate-200 bg-white p-3 shadow-[0_8px_30px_rgba(15,23,42,0.08)] focus-within:border-blue-300 focus-within:ring-2 focus-within:ring-blue-100">
+            <textarea
+              aria-label="演示消息"
+              value={input}
+              onChange={(event) => setInput(event.target.value)}
+              onKeyDown={onKeyDown}
+              placeholder="输入消息，体验流式渲染…"
+              rows={2}
+              className="w-full resize-none border-0 px-2 py-1 text-sm leading-6 outline-none placeholder:text-slate-400"
+            />
+            <div className="mt-2 flex items-center justify-between">
+              <button type="button" aria-label="添加附件（演示）" className="flex h-8 w-8 items-center justify-center rounded-full text-slate-500 hover:bg-slate-100"><Plus className="h-4 w-4" /></button>
+              <div className="flex items-center gap-2">
+                {running ? <span className="flex items-center gap-1.5 text-xs text-slate-500"><LoaderCircle className="h-3.5 w-3.5 animate-spin" /> 运行中</span> : <span className="flex items-center gap-1.5 text-xs text-emerald-600"><CheckCircle2 className="h-3.5 w-3.5" /> 可发送</span>}
+                <button
+                  type="submit"
+                  disabled={!input.trim() || running}
+                  aria-label="发送演示消息"
+                  className="flex h-9 w-9 items-center justify-center rounded-full bg-blue-600 text-white transition hover:bg-blue-500 disabled:cursor-not-allowed disabled:bg-slate-200"
+                >
+                  <Send className="h-4 w-4" />
+                </button>
+              </div>
+            </div>
+          </form>
+          <p className="mx-auto mt-2 max-w-3xl text-center text-[11px] text-slate-400">演示仅在浏览器本地运行，不发送数据。</p>
+        </div>
+      </main>
+    </div>
+  );
+}
diff --git a/src/index.css b/src/index.css
index 0ac7d4b..8bc1c34 100644
--- a/src/index.css
+++ b/src/index.css
@@ -162,6 +162,42 @@
   }
 }
 
+@keyframes waiting-thinking-text {
+  0% {
+    background-position: 140% 50%;
+  }
+  100% {
+    background-position: -40% 50%;
+  }
+}
+
+.waiting-thinking-text {
+  display: inline-block;
+  color: hsl(var(--text-muted));
+  background-image: linear-gradient(
+    90deg,
+    hsl(var(--text-muted)) 0%,
+    hsl(var(--text-muted)) 32%,
+    hsl(var(--foreground)) 50%,
+    hsl(var(--text-muted)) 68%,
+    hsl(var(--text-muted)) 100%
+  );
+  background-size: 240% 100%;
+  background-clip: text;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  animation: waiting-thinking-text 1.6s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .waiting-thinking-text {
+    animation: none;
+    background: none;
+    color: hsl(var(--text-muted));
+    -webkit-text-fill-color: currentColor;
+  }
+}
+
 .prose {
   font-size: 15px;
   line-height: 1.8;
diff --git a/src/main.tsx b/src/main.tsx
index 17c92b2..388b690 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -2,11 +2,12 @@ import ReactDOM from 'react-dom/client'
 import App from './App.tsx'
 import { ErrorBoundary } from './components/ErrorBoundary.tsx'
 import { ToastContainer } from './components/ToastContainer.tsx'
+import { DemoWorkbench } from './demo/DemoWorkbench.tsx'
 import './index.css'
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <ErrorBoundary>
-    <App />
+    {import.meta.env.VITE_DEMO_MODE === '1' ? <DemoWorkbench /> : <App />}
     <ToastContainer />
   </ErrorBoundary>,
 )
diff --git a/tests/package-contract.test.mjs b/tests/package-contract.test.mjs
index 9d12c08..0e0c518 100644
--- a/tests/package-contract.test.mjs
+++ b/tests/package-contract.test.mjs
@@ -10,7 +10,8 @@ test('package metadata exposes release artifacts and public entrypoints', () =>
   assert.match(packageJson.version, /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/);
   assert.deepEqual(packageJson.publishConfig, { access: 'public' });
   assert.equal(packageJson.scripts['build:lib'], 'vite build --config vite.lib.config.ts && tsc -p tsconfig.lib.json');
-  assert.equal(packageJson.scripts['build:all'], 'npm run build:ksadk && npm run build:hosted && npm run build:lib');
+  assert.equal(packageJson.scripts['build:demo'], 'VITE_DEMO_MODE=1 VITE_BASE_PATH=./ vite build --outDir dist-demo');
+  assert.equal(packageJson.scripts['build:all'], 'npm run build:ksadk && npm run build:hosted && npm run build:demo && npm run build:lib');
   assert.equal(packageJson.scripts['test:node'], 'node --test tests/*.test.mjs');
   assert.equal(packageJson.scripts['release:provenance'], 'node scripts/release-provenance.mjs');
   assert.equal(packageJson.scripts['release:preflight'], 'node scripts/release-preflight.mjs');
@@ -65,7 +66,7 @@ test('npm publishing uses trusted publishing instead of repository tokens', () =
 
 test('successful npm release automatically deploys the matching Pages bundle', () => {
   assert.match(publishWorkflow, /actions\/upload-pages-artifact@v3/);
-  assert.match(publishWorkflow, /path:\s+dist-ksadk/);
+  assert.match(publishWorkflow, /path:\s+dist-demo/);
   assert.match(publishWorkflow, /deploy-pages:\s*[\s\S]*needs:\s+publish/);
   assert.match(publishWorkflow, /pages:\s+write/);
   assert.match(publishWorkflow, /actions\/deploy-pages@v4/);

From 7237e2066511fe11e7f08c25b16567f559cb411d Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 17:23:09 +0800
Subject: [PATCH 06/25] chore(release): refresh ksadk-web 0.3.4 provenance

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index 6182cd3..31a07c4 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "79c5ffc66609aae39bcdc5c1c59e07a36601b71d",
+  "source_commit": "207fc6468a7ae4a904ba782f28d6c2d80def866c",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From 4a63ace692e04780468eda73193507111b576e06 Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 17:37:15 +0800
Subject: [PATCH 07/25] feat(demo): exercise approval streaming and feedback

---
 CHANGELOG.md                                 |   7 +-
 e2e/demo.spec.ts                             |  28 ++-
 src/__tests__/demo-page-contract.test.ts     |   6 +-
 src/components/chat/ChatMessageList.tsx      |  12 +-
 src/components/chat/ProcessingBlocksView.tsx |   2 +-
 src/demo/DemoWorkbench.tsx                   | 210 ++++++++++++++++---
 6 files changed, 218 insertions(+), 47 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aa7415a..aed90b1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,9 +10,10 @@
   matching WeWork's low-noise thinking treatment while preserving the compact,
   collapsible completed state.
 - Publish a dedicated interactive GitHub Pages demo that exercises the shared
-  reasoning, tool, Markdown, and composer components entirely in the browser.
-  It is explicitly labelled as local sample data instead of attempting to
-  connect to a nonexistent Agent backend.
+  reasoning, tool, approval tray, token-by-token Markdown, feedback, and
+  composer components entirely in the browser. It is explicitly labelled as
+  local sample data instead of attempting to connect to a nonexistent Agent
+  backend.
 
 ## 0.3.3 - 2026-08-28
 
diff --git a/e2e/demo.spec.ts b/e2e/demo.spec.ts
index 1e28163..dd957d2 100644
--- a/e2e/demo.spec.ts
+++ b/e2e/demo.spec.ts
@@ -1,6 +1,6 @@
 import { expect, test } from '@playwright/test';
 
-test('public demo visibly streams reasoning, a tool, and Markdown without a backend', async ({ page }) => {
+test('public demo streams reasoning, tool, approval, Markdown, and feedback without a backend', async ({ page }) => {
   await page.goto('/');
 
   await expect(page.getByRole('heading', { name: 'KsADK Web 示例 Agent' })).toBeVisible();
@@ -12,11 +12,27 @@ test('public demo visibly streams reasoning, a tool, and Markdown without a back
   await composer.fill('验证公开演示');
   await send.click();
 
-  await expect(page.getByTestId('thinking-indicator')).toHaveText('正在思考');
+  await expect(page.getByTestId('thinking-indicator')).toHaveText('正在思考…');
   await expect(page.getByTestId('thinking-indicator')).toHaveClass(/waiting-thinking-text/);
+  const thinkingAnimation = page.getByTestId('thinking-indicator');
+  await expect.poll(async () => thinkingAnimation.evaluate((element) => {
+    const animation = element.getAnimations()[0];
+    return typeof animation?.currentTime === 'number' ? animation.currentTime : 0;
+  })).toBeGreaterThan(100);
   await expect(page.getByRole('button', { name: '发送演示消息' })).toBeDisabled();
-  await expect(page.getByRole('button', { name: /正在运行 demo\.echo_context/ })).toBeVisible();
-  await expect(page.getByRole('button', { name: /已完成 demo\.echo_context/ })).toBeVisible();
-  await expect(page.getByText('已收到：“验证公开演示”。')).toBeVisible();
-  await expect(page.getByText(/组件会消费同一套会话、思考、工具、审批与 A2UI 协议/)).toBeVisible();
+  await expect(page.getByRole('button', { name: /正在运行 demo\.prepare_summary/ })).toBeVisible();
+  await expect(page.getByRole('button', { name: /已完成 demo\.prepare_summary/ })).toBeVisible();
+
+  const tray = page.getByTestId('interaction-tray');
+  await expect(tray).toBeVisible();
+  await expect(tray).toContainText('允许继续生成演示结果？');
+  await expect(tray).toContainText('批准后将继续流式输出');
+  await page.getByTestId('interaction-approve').click();
+
+  await expect(page.getByText('已批准继续执行。', { exact: true })).toBeVisible();
+  await expect(page.getByText('已收到：“验证公开演示”。', { exact: true })).toBeVisible();
+  await expect(page.getByText(/按字符增量渲染正文/)).toBeVisible();
+  await expect(page.getByText('本次回复有帮助吗？')).toBeVisible();
+  await page.getByRole('button', { name: '有帮助' }).click();
+  await expect(page.getByRole('button', { name: '删除反馈' })).toBeVisible();
 });
diff --git a/src/__tests__/demo-page-contract.test.ts b/src/__tests__/demo-page-contract.test.ts
index 2d7a89f..cbf38c0 100644
--- a/src/__tests__/demo-page-contract.test.ts
+++ b/src/__tests__/demo-page-contract.test.ts
@@ -16,6 +16,10 @@ describe('public demo page contract', () => {
     expect(demo).toContain('不会连接或冒充真实 Agent');
     expect(demo).toContain('setMessages');
     expect(demo).toContain('status: \'streaming\'');
+    expect(demo).toContain('<InteractionTray');
+    expect(demo).toContain('<FeedbackControls');
+    expect(demo).toContain('window.setInterval');
+    expect(demo).toContain('按字符增量渲染正文');
     expect(pages).toContain('npm run build:demo');
     expect(pages).toContain('path: dist-demo');
   });
@@ -29,7 +33,7 @@ describe('public demo page contract', () => {
     const styles = readFileSync(resolve(repoRoot, 'src/index.css'), 'utf8');
     expect(source).toContain("generating && 'waiting-thinking-text'");
     expect(source).toContain("data-testid={generating ? 'thinking-indicator'");
-    expect(source).toContain("generating ? '正在思考' : '已思考'");
+    expect(source).toContain("generating ? '正在思考…' : '已思考'");
     expect(styles).toContain('@keyframes waiting-thinking-text');
     expect(styles).toContain('animation: waiting-thinking-text 1.6s linear infinite');
     expect(styles).toContain('@media (prefers-reduced-motion: reduce)');
diff --git a/src/components/chat/ChatMessageList.tsx b/src/components/chat/ChatMessageList.tsx
index af83aa9..803c32e 100644
--- a/src/components/chat/ChatMessageList.tsx
+++ b/src/components/chat/ChatMessageList.tsx
@@ -618,18 +618,21 @@ function ToolPayloadBlock({
   );
 }
 
-function FeedbackControls({
+export function FeedbackControls({
   isLastMessage,
   isStreaming,
   message,
   onDeleteFeedback,
   onSubmitFeedback,
+  alwaysVisible = false,
 }: {
   isLastMessage: boolean;
   isStreaming: boolean;
   message: Message;
   onDeleteFeedback: (message: Message) => void;
   onSubmitFeedback: ChatMessageListProps['onSubmitFeedback'];
+  /** Public demo and embedded review surfaces may keep the feedback controls visible. */
+  alwaysVisible?: boolean;
 }) {
   const [commentOpen, setCommentOpen] = useState(false);
   const [comment, setComment] = useState(message.feedback?.comment || '');
@@ -652,7 +655,12 @@ function FeedbackControls({
   };
 
   return (
-    <div className="mt-2 flex flex-col gap-2 opacity-0 transition-opacity duration-150 group-hover:opacity-100 focus-within:opacity-100">
+    <div
+      className={cn(
+        'mt-2 flex flex-col gap-2 transition-opacity duration-150 focus-within:opacity-100',
+        alwaysVisible ? 'opacity-100' : 'opacity-0 group-hover:opacity-100',
+      )}
+    >
       <div className="flex flex-wrap items-center gap-1.5 text-xs text-text-muted">
         <button
           type="button"
diff --git a/src/components/chat/ProcessingBlocksView.tsx b/src/components/chat/ProcessingBlocksView.tsx
index 124aea2..a79d204 100644
--- a/src/components/chat/ProcessingBlocksView.tsx
+++ b/src/components/chat/ProcessingBlocksView.tsx
@@ -86,7 +86,7 @@ function ThinkingRow({ block }: { block: ThinkingBlock }) {
           data-testid={generating ? 'thinking-indicator' : undefined}
           role={generating ? 'status' : undefined}
         >
-          {generating ? '正在思考' : '已思考'}
+          {generating ? '正在思考…' : '已思考'}
         </span>
         {!generating && (
           <>
diff --git a/src/demo/DemoWorkbench.tsx b/src/demo/DemoWorkbench.tsx
index 6a1d90e..29cfdd2 100644
--- a/src/demo/DemoWorkbench.tsx
+++ b/src/demo/DemoWorkbench.tsx
@@ -3,7 +3,6 @@ import {
   Bot,
   CheckCircle2,
   Code2,
-  LoaderCircle,
   Plus,
   Send,
   Sparkles,
@@ -11,8 +10,11 @@ import {
 } from 'lucide-react';
 
 import { MessageMarkdown } from '../components/MessageMarkdown';
+import { FeedbackControls } from '../components/chat/ChatMessageList';
+import { InteractionTray, type InteractionTrayRespondInput } from '../components/chat/InteractionTray';
 import { ProcessingBlocksView } from '../components/chat/ProcessingBlocksView';
 import type { Message } from '../components/chat/types';
+import type { Interaction } from '../core/interaction/types';
 
 const initialMessages: Message[] = [
   {
@@ -32,24 +34,51 @@ const initialMessages: Message[] = [
         type: 'tool',
         toolName: 'demo.inspect_capabilities',
         args: '{"surface":"chat"}',
-        output: '{"streaming":true,"reasoning":true,"tools":true}',
+        output: '{"streaming":true,"reasoning":true,"tools":true,"interaction":true,"feedback":true}',
         status: 'completed',
       },
       {
         id: 'welcome-text',
         type: 'text',
-        content: '这是 **ksadk-web 交互演示**。你可以发送一条消息，观察思考、工具和正文按同一事件时间线逐步出现。',
+        content: '这是 **ksadk-web 交互演示**。发送消息后会依次出现思考、工具、审批、流式正文和反馈。',
         status: 'done',
       },
     ],
   },
 ];
 
+function createApproval(responseId: string): Interaction {
+  return {
+    interactionId: `demo-approval-${responseId}`,
+    sessionId: 'demo-session',
+    runId: responseId,
+    kind: 'approval',
+    title: '允许继续生成演示结果？',
+    message: '示例工具已准备好上下文。批准后将继续流式输出；此操作仅发生在当前浏览器。',
+    requestSchema: null,
+    presentation: null,
+    status: 'pending',
+    revision: 1,
+    createdAt: new Date().toISOString(),
+    expiresAt: null,
+    resolvedAt: null,
+    actor: null,
+    outcome: null,
+    responseSummary: null,
+    source: 'interaction_v1',
+    extensions: {},
+  };
+}
+
 export function DemoWorkbench() {
   const [messages, setMessages] = useState<Message[]>(initialMessages);
   const [input, setInput] = useState('');
   const [running, setRunning] = useState(false);
+  const [pendingInteraction, setPendingInteraction] = useState<Interaction | null>(null);
+  const [feedbackMessageId, setFeedbackMessageId] = useState<string | null>(null);
   const timers = useRef<number[]>([]);
+  const activePrompt = useRef('');
+  const activeResponseId = useRef('');
 
   useEffect(() => () => {
     timers.current.forEach((timer) => window.clearTimeout(timer));
@@ -65,13 +94,78 @@ export function DemoWorkbench() {
     )));
   };
 
+  const streamFinalResponse = (responseId: string, prompt: string) => {
+    const finalText = `已批准继续执行。\n\n已收到：“${prompt}”。\n\n这个页面正在按字符增量渲染正文。接入真实 Agent 时，同一套组件会消费会话、思考、工具、审批、A2UI 与反馈事件。`;
+    let cursor = 0;
+    setRunning(true);
+    updateResponse(responseId, (message) => ({
+      ...message,
+      responseId,
+      blocks: [
+        ...(message.blocks ?? []),
+        { id: `${responseId}-text`, type: 'text', content: '', status: 'streaming' },
+      ],
+    }));
+
+    const interval = window.setInterval(() => {
+      cursor = Math.min(cursor + 2, finalText.length);
+      const content = finalText.slice(0, cursor);
+      updateResponse(responseId, (message) => ({
+        ...message,
+        content,
+        blocks: (message.blocks ?? []).map((block) => (
+          block.id === `${responseId}-text`
+            ? { ...block, content, status: cursor >= finalText.length ? 'done' as const : 'streaming' as const }
+            : block
+        )),
+      }));
+      if (cursor >= finalText.length) {
+        window.clearInterval(interval);
+        setRunning(false);
+        setFeedbackMessageId(responseId);
+      }
+    }, 55);
+    timers.current.push(interval);
+  };
+
+  const finishRejected = (responseId: string) => {
+    const content = '已拒绝，本地演示不会继续执行该步骤。你可以重新发送消息再次体验。';
+    updateResponse(responseId, (message) => ({
+      ...message,
+      responseId,
+      content,
+      blocks: [
+        ...(message.blocks ?? []),
+        { id: `${responseId}-text`, type: 'text', content, status: 'done' },
+      ],
+    }));
+    setRunning(false);
+    setFeedbackMessageId(responseId);
+  };
+
+  const respondToInteraction = (input: InteractionTrayRespondInput) => {
+    if (!pendingInteraction || pendingInteraction.status !== 'pending') return;
+    setPendingInteraction({ ...pendingInteraction, status: 'resolving' });
+    schedule(() => {
+      setPendingInteraction(null);
+      if (input.action === 'approve') {
+        streamFinalResponse(activeResponseId.current, activePrompt.current);
+      } else {
+        finishRejected(activeResponseId.current);
+      }
+    }, 450);
+  };
+
   const submit = (event: FormEvent) => {
     event.preventDefault();
     const text = input.trim();
-    if (!text || running) return;
+    if (!text || running || pendingInteraction) return;
     const stamp = Date.now();
     const responseId = `demo-response-${stamp}`;
+    activePrompt.current = text;
+    activeResponseId.current = responseId;
     setInput('');
+    setFeedbackMessageId(null);
     setRunning(true);
     setMessages((current) => [
       ...current,
@@ -111,42 +205,64 @@ export function DemoWorkbench() {
         {
           id: `${responseId}-tool`,
           type: 'tool',
-          toolName: 'demo.echo_context',
+          toolName: 'demo.prepare_summary',
           args: JSON.stringify({ input: text }, null, 2),
           status: 'running',
         },
       ],
       tools: {
-        'demo.echo_context': {
-          name: 'demo.echo_context',
+        'demo.prepare_summary': {
+          name: 'demo.prepare_summary',
           args: JSON.stringify({ input: text }, null, 2),
           status: 'running',
         },
       },
-    })), 4000);
-    schedule(() => updateResponse(responseId, (message) => ({
-      ...message,
-      blocks: [
-        ...(message.blocks ?? []).map((block) => (
-          block.type === 'tool' ? { ...block, output: '{"ok":true}', status: 'completed' as const } : block
+    })), 3000);
+    schedule(() => {
+      updateResponse(responseId, (message) => ({
+        ...message,
+        blocks: (message.blocks ?? []).map((block) => (
+          block.type === 'tool'
+            ? { ...block, output: '{"prepared":true,"requiresApproval":true}', status: 'completed' as const }
+            : block
         )),
-        {
-          id: `${responseId}-text`,
-          type: 'text',
-          content: `已收到：“${text}”。\n\n这个页面展示的是本地可交互事件流；接入真实 Agent 时，组件会消费同一套会话、思考、工具、审批与 A2UI 协议。`,
-          status: 'done',
-        },
-      ],
-      tools: {
-        'demo.echo_context': {
-          name: 'demo.echo_context',
-          args: JSON.stringify({ input: text }, null, 2),
-          output: '{"ok":true}',
-          status: 'completed',
+        tools: {
+          'demo.prepare_summary': {
+            name: 'demo.prepare_summary',
+            args: JSON.stringify({ input: text }, null, 2),
+            output: '{"prepared":true,"requiresApproval":true}',
+            status: 'completed',
+          },
         },
+      }));
+      setRunning(false);
+      setPendingInteraction(createApproval(responseId));
+    }, 5000);
+  };
+
+  const updateFeedback = (
+    message: Message,
+    rating: 'up' | 'down',
+    comment = '',
+  ) => {
+    updateResponse(message.id, (current) => ({
+      ...current,
+      feedback: {
+        responseId: current.responseId,
+        rating,
+        comment,
+        updatedAt: new Date().toISOString(),
+        pending: false,
       },
-    })), 6500);
-    schedule(() => setRunning(false), 6700);
+    }));
+  };
+
+  const deleteFeedback = (message: Message) => {
+    updateResponse(message.id, (current) => {
+      const next = { ...current };
+      delete next.feedback;
+      return next;
+    });
   };
 
   const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
@@ -156,6 +272,8 @@ export function DemoWorkbench() {
     }
   };
 
+  const busy = running || Boolean(pendingInteraction);
+
   return (
     <div className="flex min-h-screen bg-slate-50 font-sans text-slate-800">
       <aside className="hidden w-72 shrink-0 border-r border-slate-200 bg-white lg:flex lg:flex-col">
@@ -184,7 +302,7 @@ export function DemoWorkbench() {
             <span className="flex h-9 w-9 items-center justify-center rounded-xl bg-slate-100 text-slate-600"><Bot className="h-4 w-4" /></span>
             <div>
               <h1 className="text-sm font-semibold">KsADK Web 示例 Agent</h1>
-              <p className="text-xs text-slate-500">思考 · 工具 · Markdown · 会话状态</p>
+              <p className="text-xs text-slate-500">思考 · 工具 · 审批 · 流式正文 · 反馈</p>
             </div>
           </div>
           <span className="rounded-full border border-amber-200 bg-amber-50 px-3 py-1 text-xs text-amber-700">本地交互演示</span>
@@ -193,7 +311,7 @@ export function DemoWorkbench() {
         <div className="flex-1 overflow-y-auto px-5 py-8 sm:px-8">
           <div className="mx-auto max-w-3xl space-y-6">
             <div className="rounded-2xl border border-blue-100 bg-blue-50/60 px-4 py-3 text-sm leading-6 text-blue-900">
-              <div className="flex items-center gap-2 font-medium"><Sparkles className="h-4 w-4" /> 无需后端即可体验渲染</div>
+              <div className="flex items-center gap-2 font-medium"><Sparkles className="h-4 w-4" /> 无需后端即可体验完整时间线</div>
               <p className="mt-1 text-xs text-blue-700/80">这是公开站点的示例数据，不会连接或冒充真实 Agent。生产接入请使用下方源码与文档。</p>
             </div>
 
@@ -205,32 +323,56 @@ export function DemoWorkbench() {
                 </div>
               </div>
             ) : (
-              <div key={message.id} className="rounded-2xl border border-slate-100 bg-white px-4 py-4 shadow-sm shadow-slate-900/5">
+              <div key={message.id} className="group rounded-2xl border border-slate-100 bg-white px-4 py-4 shadow-sm shadow-slate-900/5">
                 <div className="mb-2 flex items-center gap-2 text-xs font-medium text-slate-600"><Bot className="h-3.5 w-3.5" /> 示例 Agent</div>
                 <ProcessingBlocksView message={message} isStreaming={running && index === messages.length - 1} />
+                {feedbackMessageId === message.id ? (
+                  <FeedbackControls
+                    alwaysVisible
+                    isLastMessage
+                    isStreaming={false}
+                    message={message}
+                    onDeleteFeedback={deleteFeedback}
+                    onSubmitFeedback={({ message: target, rating, comment }) => updateFeedback(target, rating, comment)}
+                  />
+                ) : null}
               </div>
             ))}
           </div>
         </div>
 
         <div className="border-t border-slate-100 bg-white/95 px-4 py-4 backdrop-blur sm:px-8">
+          {pendingInteraction ? (
+            <InteractionTray
+              interactions={[pendingInteraction]}
+              activeIndex={0}
+              onSelectIndex={() => undefined}
+              onRespond={respondToInteraction}
+            />
+          ) : null}
           <form onSubmit={submit} className="mx-auto max-w-3xl rounded-[24px] border border-slate-200 bg-white p-3 shadow-[0_8px_30px_rgba(15,23,42,0.08)] focus-within:border-blue-300 focus-within:ring-2 focus-within:ring-blue-100">
             <textarea
               aria-label="演示消息"
               value={input}
               onChange={(event) => setInput(event.target.value)}
               onKeyDown={onKeyDown}
-              placeholder="输入消息，体验流式渲染…"
+              placeholder="输入消息，体验完整交互时间线…"
               rows={2}
               className="w-full resize-none border-0 px-2 py-1 text-sm leading-6 outline-none placeholder:text-slate-400"
             />
             <div className="mt-2 flex items-center justify-between">
               <button type="button" aria-label="添加附件（演示）" className="flex h-8 w-8 items-center justify-center rounded-full text-slate-500 hover:bg-slate-100"><Plus className="h-4 w-4" /></button>
               <div className="flex items-center gap-2">
-                {running ? <span className="flex items-center gap-1.5 text-xs text-slate-500"><LoaderCircle className="h-3.5 w-3.5 animate-spin" /> 运行中</span> : <span className="flex items-center gap-1.5 text-xs text-emerald-600"><CheckCircle2 className="h-3.5 w-3.5" /> 可发送</span>}
+                {pendingInteraction ? (
+                  <span className="text-xs font-medium text-amber-600">等待确认</span>
+                ) : running ? (
+                  <span className="waiting-thinking-text text-xs">运行中…</span>
+                ) : (
+                  <span className="flex items-center gap-1.5 text-xs text-emerald-600"><CheckCircle2 className="h-3.5 w-3.5" /> 可发送</span>
+                )}
                 <button
                   type="submit"
-                  disabled={!input.trim() || running}
+                  disabled={!input.trim() || busy}
                   aria-label="发送演示消息"
                   className="flex h-9 w-9 items-center justify-center rounded-full bg-blue-600 text-white transition hover:bg-blue-500 disabled:cursor-not-allowed disabled:bg-slate-200"
                 >

From da1009684ce6075d33366d7a5372d62f0ca0eb4a Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 17:37:29 +0800
Subject: [PATCH 08/25] chore(release): refresh ksadk-web 0.3.4 provenance

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index 31a07c4..4268f6a 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "207fc6468a7ae4a904ba782f28d6c2d80def866c",
+  "source_commit": "4a63ace692e04780468eda73193507111b576e06",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From 6a08d63a09214f7c19f68cff0704fec03adca37c Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 18:55:55 +0800
Subject: [PATCH 09/25] test(release): verify packed conversation admission

---
 scripts/verify-packed-conversation.mjs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/scripts/verify-packed-conversation.mjs b/scripts/verify-packed-conversation.mjs
index cdb929e..559386d 100644
--- a/scripts/verify-packed-conversation.mjs
+++ b/scripts/verify-packed-conversation.mjs
@@ -6,6 +6,7 @@ import {
   decodeConversationInput,
   decodeConversationItem,
   decodeConversationSurface,
+  preflightConversationInput,
   projectConversationItems,
 } from '@kingsoftcloud/ksadk-web/conversation';
 
@@ -18,6 +19,10 @@ const input = buildConversationInput({
   idempotencyKey: 'packed-turn-1',
   parts: [{ kind: 'text', text: 'hello from packed consumer' }],
   modelRef: 'packed-model',
+  extensions: {
+    'ksadk.approval': 'risk',
+    'ksadk.collaboration': 'default',
+  },
 });
 assert.deepEqual(decodeConversationInput(input), input);
 
@@ -30,10 +35,12 @@ const surface = decodeConversationSurface({
   inputs: [
     { name: 'text', mode: 'native' },
     { name: 'model.select', mode: 'native' },
+    { name: 'approval', mode: 'native' },
   ],
   outputs: [{ name: 'text', mode: 'native' }],
 });
 assert.equal(surface?.apiVersion, 'conversation.ksadk.io/v1');
+assert.deepEqual(preflightConversationInput(surface, input), input);
 
 const item = decodeConversationItem({
   apiVersion: 'conversation.ksadk.io/v1',

From 0215b57014e26783ef4afdfa58fee80cd7eb08be Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 18:55:55 +0800
Subject: [PATCH 10/25] chore(release): refresh ksadk-web 0.3.4 provenance

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index 4268f6a..9735e60 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "4a63ace692e04780468eda73193507111b576e06",
+  "source_commit": "6a08d63a09214f7c19f68cff0704fec03adca37c",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From b72417baf9547aa497bda225dc6e2359d611d4de Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 20:44:02 +0800
Subject: [PATCH 11/25] fix(stream): preserve runtime item identity in hosted
 replay

---
 CHANGELOG.md                                  |  17 +-
 .../chat-message-list-contract.test.ts        |  14 +-
 src/__tests__/kernel-events.test.ts           |  92 +++++++++-
 src/__tests__/recovered-run.test.ts           | 159 ++++++++++++++++++
 src/__tests__/run-engine.test.ts              |  45 +++++
 src/components/chat/ChatMessageList.tsx       |  22 ++-
 src/core/conversation/hosted.ts               |   9 +-
 src/core/run/dispatcher.ts                    |  16 +-
 src/core/stream/kernel-events.ts              |  99 ++++++++++-
 src/utils/recovered-run.ts                    |  85 +++++-----
 src/utils/session-events.js                   | 113 ++++++++++---
 11 files changed, 577 insertions(+), 94 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aed90b1..f53a55d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,13 +2,26 @@
 
 ## 0.3.4 - 2026-08-31
 
+- Normalize the real RuntimeEvent/v2 wire shape before presentation: consume
+  `item.updated.update` as a named content part, retain stable
+  `run_id / scope_id / item_id / part_id` identity, apply append versus
+  replace semantics, handle atomic `item.snapshot_replaced`, and settle failed
+  tool items instead of leaving them visibly running.
+- Give each canonical run exactly one transcript owner. Live canonical items
+  replace the same run's legacy replay projection, while reconnect rebuilds the
+  complete durable item timeline. Distinct reasoning items, repeated calls to
+  the same tool, commentary messages, and the final answer no longer collapse
+  into one row or render twice.
 - Keep a conversation turn active until an explicit run-level terminal status
   arrives. Completed user messages, tools, approvals, usage reports, and
   provider notifications no longer unlock the composer or trigger duplicate
   submissions while the agent is still running.
 - Make active reasoning visibly animated with a motion-safe text shimmer,
-  matching WeWork's low-noise thinking treatment while preserving the compact,
-  collapsible completed state.
+  matching WeWork's low-noise thinking treatment across both canonical and
+  legacy rows while preserving the compact, collapsible completed state.
+- Follow new output only while the reader remains near the bottom. Replayed
+  snapshots and terminal layout changes preserve an intentionally scrolled-up
+  viewport instead of pulling it back to the latest token.
 - Publish a dedicated interactive GitHub Pages demo that exercises the shared
   reasoning, tool, approval tray, token-by-token Markdown, feedback, and
   composer components entirely in the browser. It is explicitly labelled as
diff --git a/src/__tests__/chat-message-list-contract.test.ts b/src/__tests__/chat-message-list-contract.test.ts
index 72d897c..73fb60e 100644
--- a/src/__tests__/chat-message-list-contract.test.ts
+++ b/src/__tests__/chat-message-list-contract.test.ts
@@ -103,10 +103,22 @@ describe('chat message list contracts', () => {
     expect(source).toContain('max-h-[min(46vh,28rem)]');
     expect(source).toContain('custom-scrollbar');
     expect(source).toContain('border-slate-200/80');
-    expect(source).toContain('生成中');
+    expect(source).toContain('正在思考…');
     expect(source).toContain('leading-7');
   });
 
+  it('uses the same non-spinning shimmer for legacy reasoning rows', () => {
+    const source = readFileSync(resolve(repoRoot, 'src/components/chat/ChatMessageList.tsx'), 'utf8');
+
+    expect(source).toContain("className={cn('truncate', reasoningStreaming && 'waiting-thinking-text')}");
+    expect(source).toContain("reasoningStreaming ? '正在思考…' : '思考过程'");
+    const reasoningSection = source.slice(
+      source.indexOf('{message.reasoning ? ('),
+      source.indexOf('{message.tools', source.indexOf('{message.reasoning ? (')),
+    );
+    expect(reasoningSection).not.toContain('animate-spin');
+  });
+
   it('remeasures virtual rows when expandable content changes height', () => {
     const source = readFileSync(resolve(repoRoot, 'src/components/chat/ChatMessageList.tsx'), 'utf8');
 
diff --git a/src/__tests__/kernel-events.test.ts b/src/__tests__/kernel-events.test.ts
index e30be3a..ba5b33b 100644
--- a/src/__tests__/kernel-events.test.ts
+++ b/src/__tests__/kernel-events.test.ts
@@ -59,15 +59,77 @@ describe('KernelRunEventTranslator', () => {
   it('accumulates item.updated append deltas into cumulative snapshots', () => {
     const t = new KernelRunEventTranslator('sess-1');
     const first = t.translate(
-      itemFrame(11, 'item.updated', 'agentMessage', { op: 'replace', ...AGENT_SNAPSHOT('你好') }),
+      itemFrame(11, 'item.updated', 'agentMessage', {
+        item_id: 'message-1',
+        op: 'replace',
+        update: { part_id: 'p2', content_type: 'text', text: '你好' },
+      }),
     );
     const second = t.translate(
-      itemFrame(12, 'item.updated', 'agentMessage', { op: 'append', ...AGENT_SNAPSHOT('，世界') }),
+      itemFrame(12, 'item.updated', 'agentMessage', {
+        item_id: 'message-1',
+        op: 'append',
+        update: { part_id: 'p2', content_type: 'text', text: '，世界' },
+      }),
     );
     expect(first?.Content).toEqual({ parts: [{ text: '你好' }] });
     expect(second?.Content).toEqual({ parts: [{ text: '你好，世界' }] });
   });
 
+  it('reads item.updated from the RuntimeEvent/v2 update field', () => {
+    const t = new KernelRunEventTranslator('sess-1');
+    const first = t.translate(itemFrame(15, 'item.updated', 'agentMessage', {
+      item_id: 'message-1',
+      op: 'append',
+      update: { part_id: 'p2', content_type: 'text', text: '云端' },
+    }));
+    const second = t.translate(itemFrame(16, 'item.updated', 'agentMessage', {
+      item_id: 'message-1',
+      op: 'append',
+      update: { part_id: 'p2', content_type: 'text', text: '流式' },
+    }));
+
+    expect(first?.Content).toEqual({ parts: [{ text: '云端' }] });
+    expect(second?.Content).toEqual({ parts: [{ text: '云端流式' }] });
+  });
+
+  it('atomically replaces an open assistant item snapshot', () => {
+    const t = new KernelRunEventTranslator('sess-1');
+    t.translate(itemFrame(17, 'item.updated', 'agentMessage', {
+      item_id: 'message-1',
+      op: 'append',
+      update: { part_id: 'p2', content_type: 'text', text: '旧内容' },
+    }));
+    const replaced = t.translate(itemFrame(18, 'item.snapshot_replaced', 'agentMessage', {
+      item_id: 'message-1',
+      snapshot: { parts: [{ part_id: 'p2', content_type: 'text', text: '修正后的内容' }] },
+    }));
+
+    expect(replaced?.EventType).toBe('assistant_stream_snapshot');
+    expect(replaced?.Content).toEqual({ parts: [{ text: '修正后的内容' }] });
+    expect(replaced?.Metadata?.RuntimeItem).toMatchObject({
+      ItemId: 'message-1',
+      PartId: 'p2',
+      Operation: 'replace',
+    });
+  });
+
+  it('atomically replaces an open reasoning item snapshot', () => {
+    const t = new KernelRunEventTranslator('sess-1');
+    const replaced = t.translate(itemFrame(19, 'item.snapshot_replaced', 'reasoning', {
+      item_id: 'reasoning-1',
+      snapshot: { parts: [{ part_id: 'rp1', content_type: 'text', text: '新的推理摘要' }] },
+    }));
+
+    expect(replaced?.EventType).toBe('reasoning');
+    expect(replaced?.Content).toEqual({ parts: [{ text: '新的推理摘要' }] });
+    expect(replaced?.Metadata?.RuntimeItem).toMatchObject({
+      ItemId: 'reasoning-1',
+      PartId: 'rp1',
+      Operation: 'replace',
+    });
+  });
+
   it('translates interaction frames verbatim for the interaction adapter', () => {
     const t = new KernelRunEventTranslator('sess-1');
     const record = t.translate({
@@ -112,8 +174,34 @@ describe('KernelRunEventTranslator', () => {
     );
     expect(started?.EventType).toBe('tool_call');
     expect(started?.Metadata?.call_id).toBe('tool-1');
+    expect(started?.Metadata?.RuntimeItem).toMatchObject({
+      ItemId: 'tool-1',
+      Operation: 'replace',
+    });
     expect(completed?.EventType).toBe('tool_result');
     expect(completed?.Metadata?.call_id).toBe('tool-1');
+    expect(completed?.Metadata?.RuntimeItem).toMatchObject({
+      ItemId: 'tool-1',
+      Operation: 'completed',
+    });
+  });
+
+  it('settles a failed tool item as an identity-bound error result', () => {
+    const t = new KernelRunEventTranslator('sess-1');
+    const failed = t.translate(itemFrame(20, 'item.failed', 'commandExecution', {
+      item_id: 'tool-1',
+      error: { code: 'command_failed', message: 'permission denied' },
+    }));
+
+    expect(failed?.EventType).toBe('tool_result');
+    expect(failed?.Metadata?.call_id).toBe('tool-1');
+    expect(failed?.Metadata?.tool_output).toEqual({
+      error: { code: 'command_failed', message: 'permission denied' },
+    });
+    expect(failed?.Metadata?.RuntimeItem).toMatchObject({
+      ItemId: 'tool-1',
+      Operation: 'completed',
+    });
   });
 
   it('skips control noise and non-runtime families', () => {
diff --git a/src/__tests__/recovered-run.test.ts b/src/__tests__/recovered-run.test.ts
index e07dddf..bdf18d1 100644
--- a/src/__tests__/recovered-run.test.ts
+++ b/src/__tests__/recovered-run.test.ts
@@ -28,4 +28,163 @@ describe('mergeRecoveredRunMessages', () => {
       content: '这是一段已经恢复的完整回复。',
     });
   });
+
+  it('keeps distinct runtime message items and replaces completed reasoning snapshots', () => {
+    const runtimeItem = (
+      itemId: string,
+      operation: 'append' | 'replace' | 'completed',
+      partId = 'text-0',
+    ) => ({
+      RuntimeItem: {
+        RunId: 'run-1',
+        ScopeId: 'scope-1',
+        ItemId: itemId,
+        PartId: partId,
+        Operation: operation,
+      },
+    });
+    const events = [
+      {
+        EventId: 'reason-delta',
+        EventType: 'reasoning',
+        InvocationId: 'run-1',
+        Content: { parts: [{ text: '先分析' }] },
+        Metadata: runtimeItem('reason-1', 'append', 'reason-0'),
+      },
+      {
+        EventId: 'reason-completed',
+        EventType: 'reasoning',
+        InvocationId: 'run-1',
+        Content: { parts: [{ text: '先分析，再核对' }] },
+        Metadata: runtimeItem('reason-1', 'completed', 'reason-0'),
+      },
+      {
+        EventId: 'commentary-completed',
+        EventType: 'assistant_message',
+        InvocationId: 'run-1',
+        Content: { parts: [{ text: '我先检查目录。' }] },
+        Metadata: runtimeItem('message-1', 'completed'),
+      },
+      {
+        EventId: 'answer-completed',
+        EventType: 'assistant_message',
+        InvocationId: 'run-1',
+        Content: { parts: [{ text: '最终答案。' }] },
+        Metadata: runtimeItem('message-2', 'completed'),
+      },
+    ];
+
+    const merged = mergeRecoveredRunMessages([], events, 'run-1');
+
+    expect(merged).toHaveLength(2);
+    expect(merged.map((message) => message.itemId)).toEqual(['message-1', 'message-2']);
+    expect(merged[0]).toMatchObject({
+      content: '我先检查目录。',
+      reasoning: '先分析，再核对',
+    });
+    expect(merged[1]).toMatchObject({ content: '最终答案。' });
+  });
+
+  it('streams a later runtime item after an earlier item in the same run completed', () => {
+    const metadata = (itemId: string, operation: 'replace' | 'completed') => ({
+      RuntimeItem: {
+        RunId: 'run-1',
+        ScopeId: 'scope-1',
+        ItemId: itemId,
+        PartId: 'text-0',
+        Operation: operation,
+      },
+    });
+    const merged = mergeRecoveredRunMessages([], [
+      {
+        EventId: 'commentary-completed',
+        EventType: 'assistant_message',
+        InvocationId: 'run-1',
+        Content: { parts: [{ text: '正在检查。' }] },
+        Metadata: metadata('message-1', 'completed'),
+      },
+      {
+        EventId: 'answer-snapshot',
+        EventType: 'assistant_stream_snapshot',
+        InvocationId: 'run-1',
+        Content: { parts: [{ text: '最终答案的前半段' }] },
+        Metadata: metadata('message-2', 'replace'),
+      },
+    ], 'run-1');
+
+    expect(merged.map((message) => message.content)).toEqual([
+      '正在检查。',
+      '最终答案的前半段',
+    ]);
+  });
+
+  it('keeps repeated tool names as distinct runtime items across replay', () => {
+    const metadata = (itemId: string, operation: 'replace' | 'completed') => ({
+      call_id: itemId,
+      tool_name: 'search',
+      RuntimeItem: {
+        RunId: 'run-1',
+        ScopeId: 'scope-1',
+        ItemId: itemId,
+        Operation: operation,
+      },
+    });
+    const events = [
+      {
+        EventId: 'tool-1-start',
+        EventType: 'tool_call',
+        InvocationId: 'run-1',
+        Metadata: { ...metadata('tool-1', 'replace'), tool_args: { q: 'first' } },
+      },
+      {
+        EventId: 'tool-1-done',
+        EventType: 'tool_result',
+        InvocationId: 'run-1',
+        Metadata: { ...metadata('tool-1', 'completed'), tool_output: { value: 'one' } },
+      },
+      {
+        EventId: 'tool-2-start',
+        EventType: 'tool_call',
+        InvocationId: 'run-1',
+        Metadata: { ...metadata('tool-2', 'replace'), tool_args: { q: 'second' } },
+      },
+      {
+        EventId: 'tool-2-done',
+        EventType: 'tool_result',
+        InvocationId: 'run-1',
+        Metadata: { ...metadata('tool-2', 'completed'), tool_output: { value: 'two' } },
+      },
+    ];
+
+    const merged = mergeRecoveredRunMessages([], events, 'run-1');
+
+    expect(merged.map((message) => message.itemId)).toEqual(['tool-1', 'tool-2']);
+    expect(merged.map((message) => message.tools?.search?.output)).toEqual([
+      '{\n  "value": "one"\n}',
+      '{\n  "value": "two"\n}',
+    ]);
+  });
+
+  it('keeps consecutive reasoning items separate by RuntimeItem identity', () => {
+    const events = ['reason-1', 'reason-2'].map((itemId, index) => ({
+      EventId: `${itemId}-done`,
+      EventType: 'reasoning',
+      InvocationId: 'run-1',
+      Content: { parts: [{ text: index === 0 ? '第一段推理' : '第二段推理' }] },
+      Metadata: {
+        RuntimeItem: {
+          RunId: 'run-1',
+          ScopeId: 'scope-1',
+          ItemId: itemId,
+          PartId: 'reason-0',
+          Operation: 'completed',
+        },
+      },
+    }));
+
+    const merged = mergeRecoveredRunMessages([], events, 'run-1');
+
+    expect(merged.map((message) => message.itemId)).toEqual(['reason-1', 'reason-2']);
+    expect(merged.map((message) => message.reasoning)).toEqual(['第一段推理', '第二段推理']);
+  });
 });
diff --git a/src/__tests__/run-engine.test.ts b/src/__tests__/run-engine.test.ts
index d4b96ed..b7edb8f 100644
--- a/src/__tests__/run-engine.test.ts
+++ b/src/__tests__/run-engine.test.ts
@@ -224,6 +224,51 @@ describe('RunEngineImpl', () => {
     }));
   });
 
+  it('keeps one transcript owner when canonical and durable run projections overlap', () => {
+    useSessionStore.getState().setCurrentSessionId('session-canonical');
+    const result = canonicalResult();
+
+    dispatchRunEventToStores({
+      type: 'stream_event',
+      sessionId: 'session-canonical',
+      event: {
+        EventId: 'legacy-final-before-canonical',
+        EventType: 'assistant_message',
+        SessionId: 'session-canonical',
+        InvocationId: 'run-canonical',
+        SeqId: 10,
+        Content: { parts: [{ text: 'canonical answer' }] },
+      },
+    });
+    dispatchRunEventToStores({
+      type: 'conversation_snapshot',
+      sessionId: 'session-canonical',
+      result,
+    });
+    dispatchRunEventToStores({
+      type: 'stream_event',
+      sessionId: 'session-canonical',
+      event: {
+        EventId: 'legacy-final-after-canonical',
+        EventType: 'assistant_message',
+        SessionId: 'session-canonical',
+        InvocationId: 'run-canonical',
+        SeqId: 11,
+        Content: { parts: [{ text: 'canonical answer' }] },
+      },
+    });
+
+    const answers = useMessageStore.getState().messages.filter(
+      (message) => message.role === 'model' && message.content === 'canonical answer',
+    );
+    expect(answers).toHaveLength(1);
+    expect(answers[0]).toMatchObject({
+      eventType: 'conversation_item_v1',
+      runId: 'run-canonical',
+      itemId: 'canonical-answer',
+    });
+  });
+
   it('keeps the existing Responses path only when the conversation surface endpoint is absent', async () => {
     const calls: Record<string, unknown>[] = [];
     const conversationClient: ConversationClient = {
diff --git a/src/components/chat/ChatMessageList.tsx b/src/components/chat/ChatMessageList.tsx
index 803c32e..94e6d2d 100644
--- a/src/components/chat/ChatMessageList.tsx
+++ b/src/components/chat/ChatMessageList.tsx
@@ -808,6 +808,8 @@ function ChatMessage({
     );
   }
 
+  const reasoningStreaming = isStreaming && isLastMessage && !message.content;
+
   return (
     <div className="group mx-auto mb-3 w-full max-w-3xl px-6">
       <div className="mb-1.5 flex items-center gap-2 text-xs text-text-muted">
@@ -837,15 +839,21 @@ function ChatMessage({
         <details className="group/details mb-3 overflow-hidden rounded-md border border-slate-200/80 bg-slate-50/60 text-sm text-slate-600 transition-colors open:bg-white dark:border-slate-700/80 dark:bg-slate-900/40 dark:text-slate-300 dark:open:bg-slate-950/30">
           <summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-3 py-2 font-medium outline-none marker:hidden">
             <div className="flex min-w-0 items-center gap-2">
-              {isStreaming && isLastMessage && !message.content ? (
-                <RefreshCcw className="h-4 w-4 animate-spin text-slate-500" />
-              ) : (
+              {!reasoningStreaming ? (
                 <Check className="h-4 w-4 text-slate-400" />
-              )}
-              <span className="truncate">思考过程</span>
-              <span className="rounded-full bg-slate-200/70 px-2 py-0.5 text-[11px] font-medium text-slate-600 dark:bg-slate-800 dark:text-slate-300">
-                {isStreaming && isLastMessage && !message.content ? '生成中' : '已完成'}
+              ) : null}
+              <span
+                className={cn('truncate', reasoningStreaming && 'waiting-thinking-text')}
+                data-testid={reasoningStreaming ? 'legacy-thinking-indicator' : undefined}
+                role={reasoningStreaming ? 'status' : undefined}
+              >
+                {reasoningStreaming ? '正在思考…' : '思考过程'}
               </span>
+              {!reasoningStreaming ? (
+                <span className="rounded-full bg-slate-200/70 px-2 py-0.5 text-[11px] font-medium text-slate-600 dark:bg-slate-800 dark:text-slate-300">
+                  已完成
+                </span>
+              ) : null}
             </div>
             <ChevronDown className="h-4 w-4 flex-shrink-0 text-slate-400 transition-transform group-open/details:rotate-180" />
           </summary>
diff --git a/src/core/conversation/hosted.ts b/src/core/conversation/hosted.ts
index 30390d1..5fc37cd 100644
--- a/src/core/conversation/hosted.ts
+++ b/src/core/conversation/hosted.ts
@@ -345,8 +345,10 @@ export function projectConversationStreamForHostedUi(
 }
 
 /**
- * Replace only this run's canonical projection. Other transports and previous
- * turns remain untouched; equal text from distinct item IDs is never merged.
+ * Replace this run's transcript projection. Once a run has canonical items,
+ * the durable legacy read model for the same run is a replay source, not a
+ * second presentation owner. Other runs/transports remain untouched; equal
+ * text from distinct canonical item IDs is never merged.
  */
 export function mergeConversationRunMessages(
   previous: Message[],
@@ -354,7 +356,8 @@ export function mergeConversationRunMessages(
 ): Message[] {
   const projected = projectConversationStreamForHostedUi(result).messages;
   const belongsToRun = (message: Message) => (
-    message.eventType === EVENT_TYPE && message.runId === result.runId
+    (message.eventType === EVENT_TYPE && message.runId === result.runId)
+    || message.invocationId === result.runId
   );
   const insertionIndex = previous.findIndex(belongsToRun);
   const retained = previous.filter((message) => !belongsToRun(message));
diff --git a/src/core/run/dispatcher.ts b/src/core/run/dispatcher.ts
index b0d68c0..3da305b 100644
--- a/src/core/run/dispatcher.ts
+++ b/src/core/run/dispatcher.ts
@@ -477,9 +477,19 @@ export function dispatchRunEventToStores(event: RunEvent) {
           [event.event],
         );
         recoveredEventsByRun.set(runKey, recoveredEvents);
-        useMessageStore.getState().patchMessages((prev) =>
-          mergeRecoveredRunMessages(prev, recoveredEvents, invocationId),
-        );
+        useMessageStore.getState().patchMessages((prev) => {
+          // ConversationItem/v1 is the single presentation owner for a
+          // canonical run. SubscribeSessionEvents remains useful for durable
+          // interactions, checkpoints and lifecycle, but projecting the same
+          // output through the legacy read model creates a second live answer.
+          const canonicalOwnsRun = prev.some((message) => (
+            message.eventType === 'conversation_item_v1'
+            && message.runId === invocationId
+          ));
+          return canonicalOwnsRun
+            ? prev
+            : mergeRecoveredRunMessages(prev, recoveredEvents, invocationId);
+        });
         if (eventHasTerminalRunStatus(event.event)) {
           recoveredEventsByRun.delete(runKey);
         }
diff --git a/src/core/stream/kernel-events.ts b/src/core/stream/kernel-events.ts
index 745b9a3..a56ee43 100644
--- a/src/core/stream/kernel-events.ts
+++ b/src/core/stream/kernel-events.ts
@@ -48,10 +48,19 @@ function frameNativeKind(frame: KernelSessionEventFrame): string {
   return String(metadata?.native_item_kind || '');
 }
 
-function frameParts(frame: KernelSessionEventFrame, key: 'initial' | 'snapshot'): unknown[] {
+function frameParts(
+  frame: KernelSessionEventFrame,
+  key: 'initial' | 'update' | 'snapshot',
+): unknown[] {
   const holder = asRecord(frame[key]);
+  if (!holder) return [];
   const parts = holder?.parts;
-  return Array.isArray(parts) ? parts : [];
+  if (Array.isArray(parts)) return parts;
+  // RuntimeEvent/v2 ContentUpdate is one named part, while initial/completed
+  // values are ContentSnapshot objects. Keeping this compatibility branch
+  // local to the wire translator prevents a real delta from being mistaken
+  // for an empty terminal snapshot.
+  return key === 'update' ? [holder] : [];
 }
 
 function partText(part: unknown): string {
@@ -90,6 +99,23 @@ function toolPayload(parts: unknown[]): unknown {
   return text || null;
 }
 
+function runtimeItemMetadata(
+  frame: KernelSessionEventFrame,
+  operation: 'append' | 'replace' | 'completed',
+  partId?: string,
+): Record<string, unknown> {
+  return {
+    RuntimeItem: {
+      RunId: String(frame.run_id || ''),
+      ScopeId: String(frame.scope_id || frame.run_id || ''),
+      ItemId: String(frame.item_id || ''),
+      ...(partId ? { PartId: partId } : {}),
+      Operation: operation,
+      SourceEventId: String(frame.event_id || ''),
+    },
+  };
+}
+
 /**
  * Stateful translator: accumulates item.updated text deltas per part so the
  * emitted assistant_stream_snapshot records are cumulative (the legacy read
@@ -151,11 +177,13 @@ export class KernelRunEventTranslator {
     if (eventType === 'item.started') {
       const parts = frameParts(frame, 'initial');
       if (nativeKind === 'userMessage' || looksLikeUserMessage(parts)) return null;
+      if (nativeKind === 'reasoning' || frame.item_kind === 'reasoning') return null;
       if (nativeKind === 'agentMessage' || (!nativeKind && frame.item_kind === 'message')) {
         return {
           ...base(),
           EventType: 'assistant_stream_snapshot',
           Content: { parts: [{ text: '' }] },
+          Metadata: runtimeItemMetadata(frame, 'replace'),
         };
       }
       if (nativeKind && nativeKind !== 'notification') {
@@ -163,6 +191,7 @@ export class KernelRunEventTranslator {
           ...base(),
           EventType: 'tool_call',
           Metadata: {
+            ...runtimeItemMetadata(frame, 'replace'),
             call_id: String(frame.item_id || ''),
             tool_name: nativeKind,
             run_id: runId,
@@ -174,7 +203,7 @@ export class KernelRunEventTranslator {
     }
 
     if (eventType === 'item.updated') {
-      const parts = frameParts(frame, 'snapshot');
+      const parts = frameParts(frame, 'update');
       const part = asRecord(parts[0]);
       const partId = String(part?.part_id || frame.item_id || seq);
       const op = String(frame.op || 'replace');
@@ -187,13 +216,45 @@ export class KernelRunEventTranslator {
           ...base(),
           EventType: 'assistant_stream_snapshot',
           Content: { parts: [{ text: next }] },
+          // The emitted legacy record is cumulative even when the source was
+          // append, so downstream identity reducers must replace this part.
+          Metadata: runtimeItemMetadata(frame, 'replace', partId),
+        };
+      }
+      if (nativeKind === 'reasoning' || frame.item_kind === 'reasoning') {
+        return {
+          ...base(),
+          EventType: 'reasoning',
+          Content: { parts: [{ text: delta }] },
+          Metadata: runtimeItemMetadata(
+            frame,
+            op === 'append' ? 'append' : 'replace',
+            partId,
+          ),
+        };
+      }
+      return null;
+    }
+
+    if (eventType === 'item.snapshot_replaced') {
+      const parts = frameParts(frame, 'snapshot');
+      const partId = String(asRecord(parts[0])?.part_id || frame.item_id || seq);
+      const text = partsText(parts);
+      this.textByPart.set(partId, text);
+      if (nativeKind === 'agentMessage' || (!nativeKind && frame.item_kind === 'message')) {
+        return {
+          ...base(),
+          EventType: 'assistant_stream_snapshot',
+          Content: { parts: [{ text }] },
+          Metadata: runtimeItemMetadata(frame, 'replace', partId),
         };
       }
       if (nativeKind === 'reasoning' || frame.item_kind === 'reasoning') {
         return {
           ...base(),
           EventType: 'reasoning',
-          Content: { text: next },
+          Content: { parts: [{ text }] },
+          Metadata: runtimeItemMetadata(frame, 'replace', partId),
         };
       }
       return null;
@@ -210,21 +271,30 @@ export class KernelRunEventTranslator {
       }
       if (nativeKind === 'agentMessage' || (!nativeKind && frame.item_kind === 'message')) {
         const text = partsText(parts);
-        this.textByPart.set(String(asRecord(parts[0])?.part_id || frame.item_id || seq), text);
+        const partId = String(asRecord(parts[0])?.part_id || frame.item_id || seq);
+        this.textByPart.set(partId, text);
         return {
           ...base(),
           EventType: 'assistant_message',
           Content: { parts: [{ text }] },
+          Metadata: runtimeItemMetadata(frame, 'completed', partId),
         };
       }
       if (nativeKind === 'reasoning' || frame.item_kind === 'reasoning') {
-        return { ...base(), EventType: 'reasoning', Content: { text: partsText(parts) } };
+        const partId = String(asRecord(parts[0])?.part_id || frame.item_id || seq);
+        return {
+          ...base(),
+          EventType: 'reasoning',
+          Content: { parts: [{ text: partsText(parts) }] },
+          Metadata: runtimeItemMetadata(frame, 'completed', partId),
+        };
       }
       if (nativeKind && nativeKind !== 'notification') {
         return {
           ...base(),
           EventType: 'tool_result',
           Metadata: {
+            ...runtimeItemMetadata(frame, 'completed'),
             call_id: String(frame.item_id || ''),
             tool_name: nativeKind,
             run_id: runId,
@@ -235,6 +305,23 @@ export class KernelRunEventTranslator {
       return null;
     }
 
+    if (eventType === 'item.failed') {
+      if (nativeKind && nativeKind !== 'notification' && nativeKind !== 'agentMessage' && nativeKind !== 'reasoning') {
+        return {
+          ...base(),
+          EventType: 'tool_result',
+          Metadata: {
+            ...runtimeItemMetadata(frame, 'completed'),
+            call_id: String(frame.item_id || ''),
+            tool_name: nativeKind,
+            run_id: runId,
+            tool_output: { error: asRecord(frame.error) || frame.error || 'item failed' },
+          },
+        };
+      }
+      return null;
+    }
+
     return null;
   }
 }
diff --git a/src/utils/recovered-run.ts b/src/utils/recovered-run.ts
index 3d4db8d..0febf46 100644
--- a/src/utils/recovered-run.ts
+++ b/src/utils/recovered-run.ts
@@ -3,58 +3,49 @@ import { buildBlocksFromHistory } from '../core/run/blocks.js';
 import type { SessionEventRecord } from '../types/session-events.js';
 import { buildMessagesFromSessionEvents } from './session-events.js';
 
-function mergeRecoveredText(existing: string | undefined, recovered: string | undefined): string {
-  const previous = String(existing || '');
-  const next = String(recovered || '');
-  if (!previous || !next || previous.endsWith(next)) return previous || next;
-  if (next.startsWith(previous)) return next;
-  return `${previous}${next}`;
-}
-
-function mergeRecoveredTools(
-  existing: Message['tools'] | undefined,
-  recovered: Message['tools'] | undefined,
-): Message['tools'] | undefined {
-  if (!existing) return recovered;
-  if (!recovered) return existing;
-  return Object.fromEntries(
-    [...new Set([...Object.keys(existing), ...Object.keys(recovered)])].map((key) => [
-      key,
-      { ...(existing[key] || {}), ...(recovered[key] || {}) },
-    ]),
-  ) as Message['tools'];
-}
-
 export function mergeRecoveredRunMessages(
   messages: Message[],
   events: SessionEventRecord[],
   invocationId: string,
 ): Message[] {
-  const recovered = (buildMessagesFromSessionEvents(events) as Message[])
-    .filter((message) => message.role === 'model')
-    .at(-1);
-  if (!recovered) return messages;
+  const existingOwned = messages.filter((message) => (
+    message.role === 'model' && message.invocationId === invocationId
+  ));
+  const rawRecovered = (buildMessagesFromSessionEvents(events) as Message[])
+    .filter((message) => message.role === 'model');
+  const recovered = rawRecovered
+    .map((message) => ({
+      ...message,
+      // Old SessionEvent producers have no RuntimeItem identity. Preserve the
+      // existing row id for their single assistant projection so React does
+      // not remount the message on every snapshot.
+      id: !message.itemId && rawRecovered.length === 1
+        ? existingOwned[0]?.id || `${invocationId}:assistant`
+        : message.id,
+      invocationId,
+      blocks: buildBlocksFromHistory({
+        content: message.content,
+        reasoning: message.reasoning,
+        tools: message.tools,
+      }),
+    }));
+  if (recovered.length === 0) return messages;
 
-  const existingIndex = messages.findIndex((message) =>
-    message.role === 'model' && message.invocationId === invocationId,
-  );
-  const existing = existingIndex >= 0 ? messages[existingIndex] : undefined;
-  const content = mergeRecoveredText(existing?.content, recovered.content);
-  const reasoning = mergeRecoveredText(existing?.reasoning, recovered.reasoning);
-  const tools = mergeRecoveredTools(existing?.tools, recovered.tools);
-  const merged: Message = {
-    ...existing,
+  // Re-project the complete durable run snapshot on every event. This is the
+  // same model used by Wework/VeADK: stable item identity owns rows; a terminal
+  // snapshot replaces an item and never concatenates with the previous render.
+  const firstOwnedIndex = messages.findIndex((message) => (
+    message.role === 'model' && message.invocationId === invocationId
+  ));
+  const retained = messages.filter((message) => !(
+    message.role === 'model' && message.invocationId === invocationId
+  ));
+  const insertionIndex = firstOwnedIndex < 0
+    ? retained.length
+    : Math.min(firstOwnedIndex, retained.length);
+  return [
+    ...retained.slice(0, insertionIndex),
     ...recovered,
-    id: existing?.id || recovered.id || `${invocationId}:assistant`,
-    invocationId,
-    content,
-    reasoning,
-    tools,
-    blocks: buildBlocksFromHistory({ content, reasoning, tools }),
-  };
-
-  if (existingIndex < 0) {
-    return [...messages, merged];
-  }
-  return messages.map((message, index) => (index === existingIndex ? merged : message));
+    ...retained.slice(insertionIndex),
+  ];
 }
diff --git a/src/utils/session-events.js b/src/utils/session-events.js
index abd0ba8..a47ae91 100644
--- a/src/utils/session-events.js
+++ b/src/utils/session-events.js
@@ -394,6 +394,14 @@ function buildCompactionLabel(trigger, status, historical) {
 }
 
 function assistantOutputDedupeKey(invocationId, message) {
+  if (message?.itemId) {
+    return [
+      'runtime-item',
+      message.runId || invocationId,
+      message.scopeId || invocationId,
+      message.itemId,
+    ].join('\u0000');
+  }
   return [
     invocationId,
     message.content || '',
@@ -401,6 +409,32 @@ function assistantOutputDedupeKey(invocationId, message) {
   ].join('\u0000');
 }
 
+function assistantEventProjectionKey(event) {
+  const invocationId = String(event?.InvocationId || '').trim();
+  const runtimeItem = event?.Metadata?.RuntimeItem;
+  if (runtimeItem?.ItemId) {
+    return [
+      'runtime-item',
+      runtimeItem.RunId || invocationId,
+      runtimeItem.ScopeId || invocationId,
+      runtimeItem.ItemId,
+    ].join('\u0000');
+  }
+  return invocationId;
+}
+
+function runtimeIdentityFromEvent(event) {
+  const runtimeItem = event?.Metadata?.RuntimeItem;
+  if (!runtimeItem?.ItemId) return null;
+  return {
+    id: `runtime:${runtimeItem.RunId || event.InvocationId || 'run'}:${runtimeItem.ScopeId || event.InvocationId || 'scope'}:${runtimeItem.ItemId}`,
+    runId: String(runtimeItem.RunId || event.InvocationId || ''),
+    scopeId: String(runtimeItem.ScopeId || event.InvocationId || ''),
+    itemId: String(runtimeItem.ItemId),
+    partId: runtimeItem.PartId ? String(runtimeItem.PartId) : undefined,
+  };
+}
+
 function isResponsesMirrorEvent(event) {
   return event?.Metadata?.responses_mirror === true
     || String(event?.Metadata?.responses_mirror || '').trim().toLowerCase() === 'true';
@@ -494,12 +528,14 @@ function toolMessageFromSessionEvent(event) {
               ?? {},
           ),
         };
+  const runtimeIdentity = runtimeIdentityFromEvent(event);
   return {
-    id: event.EventId || String(Date.now() + Math.random()),
+    id: runtimeIdentity?.id || event.EventId || String(Date.now() + Math.random()),
     role: 'model',
     content: '',
     timestamp: event.Timestamp || Date.now(),
     eventType,
+    ...(runtimeIdentity || {}),
     tools: {
       [name]: tool,
     },
@@ -547,10 +583,7 @@ function mergeMessageMetadata(existing, incoming) {
   return {
     ...existing,
     reasoning: mergeReasoningText(existing.reasoning, incoming.reasoning),
-    tools: {
-      ...(existing.tools || {}),
-      ...(incoming.tools || {}),
-    },
+    tools: mergeToolMaps(existing.tools, incoming.tools),
     eventId: incoming.eventId || existing.eventId,
     responseId: incoming.responseId || existing.responseId,
     traceId: incoming.traceId || existing.traceId,
@@ -603,6 +636,7 @@ export function buildCompactionMessage(options) {
  */
 export function buildMessageFromSessionEvent(event) {
   const eventType = event?.EventType || '';
+  const runtimeIdentity = runtimeIdentityFromEvent(event);
   if (eventType === 'run_status') {
     if (event.Content?.status === 'failed') {
       return {
@@ -645,12 +679,13 @@ export function buildMessageFromSessionEvent(event) {
     const reasoning = parsed.text || textFromUnknown(event.Metadata?.reasoning);
     return reasoning
       ? {
-          id: event.EventId || String(Date.now() + Math.random()),
+          id: runtimeIdentity?.id || event.EventId || String(Date.now() + Math.random()),
           role: 'model',
           content: '',
           reasoning,
           timestamp: event.Timestamp || Date.now(),
           eventType,
+          ...(runtimeIdentity || {}),
         }
       : null;
   }
@@ -686,7 +721,7 @@ export function buildMessageFromSessionEvent(event) {
   ).trim();
 
   return {
-    id: event.EventId || String(Date.now() + Math.random()),
+    id: runtimeIdentity?.id || event.EventId || String(Date.now() + Math.random()),
     role: eventType === 'user_message' ? 'user' : 'model',
     content: parsed.text,
     timestamp: event.Timestamp || Date.now(),
@@ -696,6 +731,7 @@ export function buildMessageFromSessionEvent(event) {
     traceId: traceId || undefined,
     rootSpanId: rootSpanId || undefined,
     attachments: parsed.attachments,
+    ...(runtimeIdentity || {}),
     ...responsesEnhancements,
   };
 }
@@ -724,22 +760,22 @@ export function buildMessagesFromSessionEvents(events = []) {
     uniqueEvents.push(event);
   }
   const canonicalUserMessageKeys = new Set();
-  const finalAssistantInvocations = new Set();
-  const latestSnapshotByInvocation = new Map();
+  const finalAssistantKeys = new Set();
+  const latestSnapshotByKey = new Map();
   for (const event of uniqueEvents) {
     if (event?.EventType !== 'user_message' || isResponsesMirrorEvent(event)) {
       if (event?.EventType === 'assistant_message') {
-        const invocationId = String(event.InvocationId || '').trim();
-        if (invocationId) {
-          finalAssistantInvocations.add(invocationId);
+        const projectionKey = assistantEventProjectionKey(event);
+        if (projectionKey) {
+          finalAssistantKeys.add(projectionKey);
         }
       }
       if (isAssistantStreamSnapshotEvent(event)) {
-        const invocationId = String(event.InvocationId || '').trim();
-        if (invocationId) {
-          const existing = latestSnapshotByInvocation.get(invocationId);
+        const projectionKey = assistantEventProjectionKey(event);
+        if (projectionKey) {
+          const existing = latestSnapshotByKey.get(projectionKey);
           if (!existing || eventOrderValue(event) >= eventOrderValue(existing)) {
-            latestSnapshotByInvocation.set(invocationId, event);
+            latestSnapshotByKey.set(projectionKey, event);
           }
         }
       }
@@ -752,14 +788,14 @@ export function buildMessagesFromSessionEvents(events = []) {
   }
   const replayEvents = uniqueEvents.filter((event) => {
     if (isAssistantStreamSnapshotEvent(event)) {
-      const invocationId = String(event.InvocationId || '').trim();
-      if (!invocationId) {
+      const projectionKey = assistantEventProjectionKey(event);
+      if (!projectionKey) {
         return true;
       }
-      if (finalAssistantInvocations.has(invocationId)) {
+      if (finalAssistantKeys.has(projectionKey)) {
         return false;
       }
-      return latestSnapshotByInvocation.get(invocationId) === event;
+      return latestSnapshotByKey.get(projectionKey) === event;
     }
     if (event?.EventType !== 'user_message' || !isResponsesMirrorEvent(event)) {
       return true;
@@ -792,12 +828,21 @@ export function buildMessagesFromSessionEvents(events = []) {
   /** @type {Array<Message & { invocationId?: string }>} */
   const messages = [];
   const responseIdToIndex = new Map();
+  const runtimeItemToIndex = new Map();
   /** @type {(Message & { invocationId?: string }) | null} */
   let pendingReasoning = null;
   /** @type {Map<string, Message & { invocationId?: string }>} */
   const pendingToolsByInvocation = new Map();
 
   const pushMessage = (message) => {
+    const runtimeItemKey = message?.itemId
+      ? `${message.runId || message.invocationId || ''}\u0000${message.scopeId || message.invocationId || ''}\u0000${message.itemId}`
+      : '';
+    const runtimeItemIndex = runtimeItemKey ? runtimeItemToIndex.get(runtimeItemKey) : undefined;
+    if (runtimeItemIndex !== undefined) {
+      messages[runtimeItemIndex] = mergeMessageMetadata(messages[runtimeItemIndex], message);
+      return;
+    }
     const responseId = String(message?.responseId || '').trim();
     const existingIndex = responseId ? responseIdToIndex.get(responseId) : undefined;
     if (existingIndex !== undefined) {
@@ -807,6 +852,9 @@ export function buildMessagesFromSessionEvents(events = []) {
     if (responseId) {
       responseIdToIndex.set(responseId, messages.length);
     }
+    if (runtimeItemKey) {
+      runtimeItemToIndex.set(runtimeItemKey, messages.length);
+    }
     messages.push(message);
   };
 
@@ -849,6 +897,11 @@ export function buildMessagesFromSessionEvents(events = []) {
     }
     if (TOOL_EVENT_TYPES.has(message.eventType)) {
       const invocationId = String(event.InvocationId || '').trim();
+      if (message.itemId) {
+        flushPendingReasoning();
+        pushMessage(message);
+        continue;
+      }
       if (!invocationId) {
         flushPendingReasoning();
         pushMessage(message);
@@ -873,12 +926,26 @@ export function buildMessagesFromSessionEvents(events = []) {
     }
     if (message.eventType === 'reasoning') {
       const invocationId = String(event.InvocationId || '').trim();
+      const runtimeOperation = String(event.Metadata?.RuntimeItem?.Operation || '').toLowerCase();
+      const sameRuntimeItem = Boolean(
+        message.itemId
+        && pendingReasoning?.itemId === message.itemId
+        && pendingReasoning?.runId === message.runId
+        && pendingReasoning?.scopeId === message.scopeId,
+      );
+      const sameLegacyInvocation = Boolean(
+        !message.itemId
+        && !pendingReasoning?.itemId
+        && invocationId
+        && pendingReasoning?.invocationId === invocationId,
+      );
       if (
         pendingReasoning &&
-        invocationId &&
-        pendingReasoning.invocationId === invocationId
+        (sameRuntimeItem || sameLegacyInvocation)
       ) {
-        pendingReasoning.reasoning = `${pendingReasoning.reasoning || ''}${message.reasoning || ''}`;
+        pendingReasoning.reasoning = runtimeOperation === 'replace' || runtimeOperation === 'completed'
+          ? message.reasoning
+          : `${pendingReasoning.reasoning || ''}${message.reasoning || ''}`;
         pendingReasoning.timestamp = message.timestamp;
         continue;
       }

From b053bb0ccfdfb281dbd827b04f729129f3a1d0bf Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 20:44:27 +0800
Subject: [PATCH 12/25] chore(release): refresh ksadk-web 0.3.4 provenance

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index 9735e60..a615855 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "6a08d63a09214f7c19f68cff0704fec03adca37c",
+  "source_commit": "b72417baf9547aa497bda225dc6e2359d611d4de",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From 905a146e9a75614c5624d190e89ee3dc5103a41c Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 21:09:09 +0800
Subject: [PATCH 13/25] fix(chat): keep restored session history after reload

---
 e2e/reconnect.spec.mjs                           | 15 +++++++++++++++
 src/App.tsx                                      |  3 +--
 src/__tests__/chat-message-list-contract.test.ts |  5 +++++
 3 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/e2e/reconnect.spec.mjs b/e2e/reconnect.spec.mjs
index a363118..fe0cbea 100644
--- a/e2e/reconnect.spec.mjs
+++ b/e2e/reconnect.spec.mjs
@@ -152,6 +152,9 @@ async function installReconnectFixture(page, options = {}) {
       };
     }
     if (action === 'ListSessionMessages') {
+      if (options.delayListMessagesMs) {
+        await new Promise((resolve) => setTimeout(resolve, options.delayListMessagesMs));
+      }
       payload = body.SessionId === SESSION_ID
         ? {
             Messages: [{
@@ -238,6 +241,18 @@ test('keeps the recovered assistant snapshot visible until the next snapshot arr
   await expect(page.getByText('连接断开或生成出错，请重试')).toHaveCount(0);
 });
 
+test('does not lose restored history when bootstrap state rerenders during a delayed load', async ({ page }) => {
+  const fixture = await installReconnectFixture(page, {
+    holdSubscription: true,
+    delayListMessagesMs: 350,
+    initialAssistantText: '刷新后仍应恢复的完整历史。',
+  });
+
+  await page.goto('/');
+  await expect(page.getByText('刷新后仍应恢复的完整历史。', { exact: true })).toBeVisible();
+  fixture.releaseSubscription();
+});
+
 test('renders a recovered numbered skill table as GFM instead of raw pipe text', async ({ page }) => {
   await installReconnectFixture(page);
   await page.route('**/agentengine/api/v1/SubscribeRunEvents**', async (route) => {
diff --git a/src/App.tsx b/src/App.tsx
index 19b282e..21b9dd4 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -254,9 +254,8 @@ export function AgentWorkbench({ apiAdapter, initialSurface = 'chat', routeShell
 
   useEffect(() => {
     agentIdRef.current = agentId;
-    currentSessionIdRef.current = currentSessionId;
     writePersistedSessionId(agentId, currentSessionId);
-  }, [agentId, currentSessionId, agentIdRef, currentSessionIdRef]);
+  }, [agentId, currentSessionId, agentIdRef]);
 
   useEffect(() => {
     if (!isMobile) {
diff --git a/src/__tests__/chat-message-list-contract.test.ts b/src/__tests__/chat-message-list-contract.test.ts
index 73fb60e..f4278d3 100644
--- a/src/__tests__/chat-message-list-contract.test.ts
+++ b/src/__tests__/chat-message-list-contract.test.ts
@@ -243,6 +243,11 @@ describe('chat message list contracts', () => {
     const dispatcherSource = readFileSync(resolve(repoRoot, 'src/core/run/dispatcher.ts'), 'utf8');
 
     expect(appSource).not.toContain('void loadSession(sessionId);');
+    // The lifecycle hook owns this imperative ref. Mirroring a stale React
+    // render back into it can invalidate the in-flight restored-history load:
+    // the header keeps the selected session while the transcript stays empty
+    // until the user clicks the same session again.
+    expect(appSource).not.toContain('currentSessionIdRef.current = currentSessionId;');
     expect(appSource).toContain('clearSessionMessageHistory(sessionId)');
     expect(lifecycleSource).toContain('const isStillCurrentSession = () => (');
     expect(lifecycleSource).toContain('loadSessionGenerationRef.current === generation');

From b93018445b48469480d83d809dc0a01093df63b6 Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 21:09:59 +0800
Subject: [PATCH 14/25] chore(release): refresh ksadk-web 0.3.4 provenance

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index a615855..c5f37f3 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "b72417baf9547aa497bda225dc6e2359d611d4de",
+  "source_commit": "905a146e9a75614c5624d190e89ee3dc5103a41c",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From 6f6c50222abe7bdc61706dd4d32e8a0108b687f6 Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 21:36:56 +0800
Subject: [PATCH 15/25] fix(chat): rebuild history from canonical runtime
 events

---
 CHANGELOG.md                                  |   5 +
 e2e/reconnect.spec.mjs                        | 172 +++++++++++++++++-
 .../chat-message-list-contract.test.ts        |  18 +-
 src/__tests__/session-event-history.test.ts   |   5 +-
 src/hooks/useSessionLifecycle.ts              |  67 +++++--
 src/utils/persisted-session-history.ts        | 167 +++++++++++++++++
 src/utils/session-event-history.ts            |  26 +--
 7 files changed, 406 insertions(+), 54 deletions(-)
 create mode 100644 src/utils/persisted-session-history.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f53a55d..bee7f3c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,11 @@
   complete durable item timeline. Distinct reasoning items, repeated calls to
   the same tool, commentary messages, and the final answer no longer collapse
   into one row or render twice.
+- Rebuild refreshed sessions from the complete persisted RuntimeEvent/v2 log
+  instead of rendering every cumulative `ListSessionMessages` snapshot as a
+  separate answer. Canonical runs retain item identity across reload, while
+  historical runtimes without canonical events continue to use the projected
+  message API as a compatibility fallback.
 - Keep a conversation turn active until an explicit run-level terminal status
   arrives. Completed user messages, tools, approvals, usage reports, and
   provider notifications no longer unlock the composer or trigger duplicate
diff --git a/e2e/reconnect.spec.mjs b/e2e/reconnect.spec.mjs
index fe0cbea..83700da 100644
--- a/e2e/reconnect.spec.mjs
+++ b/e2e/reconnect.spec.mjs
@@ -77,6 +77,82 @@ function assistantSnapshot(text, seqId) {
   };
 }
 
+function canonicalRuntimeRecord({
+  seqId,
+  eventType,
+  itemId,
+  itemKind,
+  nativeKind,
+  text = '',
+  operation = 'replace',
+}) {
+  const runtimeEvent = {
+    schema_version: 2,
+    event_id: `canonical-${seqId}`,
+    seq: seqId,
+    timestamp: 1788180974 + seqId,
+    run_id: INVOCATION_ID,
+    scope_id: `scope-${INVOCATION_ID}`,
+    source: {
+      framework: 'codex',
+      metadata: { native_item_kind: nativeKind },
+    },
+    event_type: eventType,
+    item_id: itemId,
+    item_kind: itemKind,
+    ...(eventType === 'item.updated'
+      ? {
+          op: operation,
+          update: {
+            content_type: 'text',
+            part_id: `${itemId}-part`,
+            text,
+          },
+        }
+      : {
+          snapshot: {
+            parts: [{
+              content_type: 'text',
+              part_id: `${itemId}-part`,
+              text,
+              data: nativeKind === 'userMessage'
+                ? { type: 'userMessage', content: [{ text }] }
+                : undefined,
+            }],
+          },
+        }),
+  };
+  const sessionEvent = {
+    schema_version: 1,
+    event_id: `session-${seqId}`,
+    session_id: SESSION_ID,
+    seq: seqId,
+    timestamp: new Date(1788180974000 + seqId * 1000).toISOString(),
+    family: 'runtime',
+    family_version: 2,
+    event_type: eventType,
+    payload: runtimeEvent,
+    run_id: INVOCATION_ID,
+  };
+  return {
+    EventId: `record-${seqId}`,
+    SessionId: SESSION_ID,
+    Author: 'codex',
+    EventType: eventType,
+    Content: { session_event: sessionEvent, runtime_event: runtimeEvent },
+    Metadata: {
+      ksadk_session_event_envelope: true,
+      schema_version: 1,
+      family: 'runtime',
+      family_version: 2,
+      canonical_event_id: sessionEvent.event_id,
+      run_id: INVOCATION_ID,
+    },
+    SeqId: seqId,
+    Timestamp: sessionEvent.timestamp,
+  };
+}
+
 async function installReconnectFixture(page, options = {}) {
   let releaseSubscription;
   const subscriptionGate = options.holdSubscription
@@ -120,8 +196,8 @@ async function installReconnectFixture(page, options = {}) {
             AgentId: 'fixture-agent',
             Title: '正在生成的会话',
             UpdatedAt: updatedAt,
-            ActiveRunStatus: '',
-            ActiveInvocationId: INVOCATION_ID,
+            ActiveRunStatus: options.completedSession ? 'completed' : '',
+            ActiveInvocationId: options.completedSession ? '' : INVOCATION_ID,
           },
           {
             SessionId: OTHER_SESSION_ID,
@@ -144,8 +220,8 @@ async function installReconnectFixture(page, options = {}) {
           ? {
               SessionId: SESSION_ID,
               AgentId: 'fixture-agent',
-              ActiveRunStatus: '',
-              ActiveInvocationId: INVOCATION_ID,
+              ActiveRunStatus: options.completedSession ? 'completed' : '',
+              ActiveInvocationId: options.completedSession ? '' : INVOCATION_ID,
               UpdatedAt: updatedAt,
             }
           : { SessionId: OTHER_SESSION_ID, AgentId: 'fixture-agent', ActiveRunStatus: 'completed' },
@@ -155,7 +231,14 @@ async function installReconnectFixture(page, options = {}) {
       if (options.delayListMessagesMs) {
         await new Promise((resolve) => setTimeout(resolve, options.delayListMessagesMs));
       }
-      payload = body.SessionId === SESSION_ID
+      payload = body.SessionId === SESSION_ID && options.persistedSnapshots
+        ? {
+            Messages: options.persistedSnapshots,
+            LatestSeqId: options.sessionEvents?.at(-1)?.SeqId ?? options.persistedSnapshots.length,
+            HasMore: false,
+            NextCursor: null,
+          }
+        : body.SessionId === SESSION_ID
         ? {
             Messages: [{
               MessageId: 'partial-runtime-message',
@@ -180,6 +263,21 @@ async function installReconnectFixture(page, options = {}) {
             NextCursor: null,
           };
     }
+    if (action === 'ListSessionEvents') {
+      const sourceEvents = body.SessionId === SESSION_ID
+        ? (options.sessionEvents ?? [])
+        : [];
+      const offset = Number(body.Offset ?? 0);
+      const limit = Number(body.Limit ?? (sourceEvents.length || 1));
+      const end = Math.max(sourceEvents.length - offset, 0);
+      const start = Math.max(end - limit, 0);
+      payload = {
+        Events: sourceEvents.slice(start, end),
+        Total: sourceEvents.length,
+        Offset: offset,
+        Limit: limit,
+      };
+    }
     await route.fulfill({
       status: 200,
       contentType: 'application/json',
@@ -253,6 +351,70 @@ test('does not lose restored history when bootstrap state rerenders during a del
   fixture.releaseSubscription();
 });
 
+test('rebuilds persisted canonical history once instead of rendering every cumulative message snapshot', async ({ page }) => {
+  const sessionEvents = [
+    canonicalRuntimeRecord({
+      seqId: 1,
+      eventType: 'item.completed',
+      itemId: 'user-1',
+      itemKind: 'message',
+      nativeKind: 'userMessage',
+      text: '请继续。',
+    }),
+    canonicalRuntimeRecord({
+      seqId: 2,
+      eventType: 'item.updated',
+      itemId: 'reasoning-1',
+      itemKind: 'reasoning',
+      nativeKind: 'reasoning',
+      text: '唯一思考过程',
+      operation: 'append',
+    }),
+    canonicalRuntimeRecord({
+      seqId: 3,
+      eventType: 'item.completed',
+      itemId: 'message-1',
+      itemKind: 'message',
+      nativeKind: 'agentMessage',
+      text: '唯一最终答复',
+    }),
+  ];
+  await installReconnectFixture(page, {
+    completedSession: true,
+    sessionEvents,
+    persistedSnapshots: [
+      {
+        MessageId: 'snapshot-1',
+        Role: 'assistant',
+        Content: { text: '唯一最终答复' },
+        InvocationId: INVOCATION_ID,
+        Reasoning: [{ text: '唯一思考过程' }],
+        SeqId: 2,
+      },
+      {
+        MessageId: 'snapshot-2',
+        Role: 'assistant',
+        Content: { text: '唯一最终答复' },
+        InvocationId: INVOCATION_ID,
+        Reasoning: [{ text: '唯一思考过程' }],
+        SeqId: 3,
+      },
+    ],
+  });
+
+  await page.goto('/');
+
+  await expect(page.getByText('唯一最终答复', { exact: true })).toHaveCount(1);
+  await expect(page.getByRole('button', { name: /已思考 · 6 字/ })).toHaveCount(1);
+  await page.getByRole('button', { name: /已思考 · 6 字/ }).click();
+  await expect(page.getByText('唯一思考过程', { exact: true })).toHaveCount(1);
+  await page.reload();
+  await expect(page.getByText('唯一最终答复', { exact: true })).toHaveCount(1);
+  await expect(page.getByRole('button', { name: /已思考 · 6 字/ })).toHaveCount(1);
+  await page.getByRole('button', { name: /已思考 · 6 字/ }).click();
+  await expect(page.getByText('唯一思考过程', { exact: true })).toHaveCount(1);
+});
+
 test('renders a recovered numbered skill table as GFM instead of raw pipe text', async ({ page }) => {
   await installReconnectFixture(page);
   await page.route('**/agentengine/api/v1/SubscribeRunEvents**', async (route) => {
diff --git a/src/__tests__/chat-message-list-contract.test.ts b/src/__tests__/chat-message-list-contract.test.ts
index f4278d3..e1a52f9 100644
--- a/src/__tests__/chat-message-list-contract.test.ts
+++ b/src/__tests__/chat-message-list-contract.test.ts
@@ -176,24 +176,22 @@ describe('chat message list contracts', () => {
     expect(listSource).toContain('取消运行并保留最近 checkpoint');
   });
 
-  it('uses projected message cursors without duplicating raw event history loads', () => {
+  it('uses canonical event history as the transcript owner with projected messages as fallback', () => {
     const lifecycleSource = readFileSync(resolve(repoRoot, 'src/hooks/useSessionLifecycle.ts'), 'utf8');
 
     expect(lifecycleSource).toContain('loadOlderSessionMessages');
     expect(lifecycleSource).toContain('beforeSeqId: historyState.nextCursor');
     expect(lifecycleSource).toContain('SESSION_MESSAGES_PAGE_SIZE');
-    // Raw event history must not be loaded for the transcript. The only
-    // allowed listSessionEvents call is the Interaction/v1 pending
-    // replay (0.3.2), which ingests durable interaction facts only and
-    // never issues a submit.
+    // Canonical RuntimeEvent/v2 replay owns new-run transcripts. The durable
+    // message projection is retained only for legacy runs and pagination.
     const listSessionEventsCalls = lifecycleSource
       .split('\n')
       .filter((line) => line.includes('api.listSessionEvents(sessionId'));
-    expect(listSessionEventsCalls).toHaveLength(1);
-    expect(listSessionEventsCalls[0]).toContain('limit: 50');
-    expect(
-      lifecycleSource.indexOf('api.listSessionEvents(sessionId'),
-    ).toBeGreaterThan(lifecycleSource.indexOf('Interaction/v1'));
+    expect(listSessionEventsCalls).toHaveLength(0);
+    expect(lifecycleSource).toContain('loadCompleteSessionEventHistory(');
+    expect(lifecycleSource).toContain('rebuildPersistedSessionHistory(');
+    expect(lifecycleSource).toContain('SESSION_EVENTS_PAGE_SIZE = 500');
+    expect(lifecycleSource).toContain('canonicalRunIdsBySessionRef');
     expect(lifecycleSource).toContain("console.warn('[SessionLifecycle] checkpoint load failed:'");
     expect(lifecycleSource).toContain("console.warn('[SessionLifecycle] tool receipt load failed:'");
   });
diff --git a/src/__tests__/session-event-history.test.ts b/src/__tests__/session-event-history.test.ts
index 76a8685..0fa946a 100644
--- a/src/__tests__/session-event-history.test.ts
+++ b/src/__tests__/session-event-history.test.ts
@@ -42,7 +42,6 @@ describe('session event history loading', () => {
     );
     expect(result?.total).toBe(306);
     expect(calls).toEqual([
-      { offset: 0, limit: 1 },
       { offset: 0, limit: 50 },
       { offset: 50, limit: 50 },
       { offset: 100, limit: 50 },
@@ -75,12 +74,12 @@ describe('session event history loading', () => {
       },
       {
         pageSize: 50,
-        shouldContinue: () => calls < 2,
+        shouldContinue: () => calls < 1,
       },
     );
 
     expect(result).toBeNull();
-    expect(calls).toBe(2);
+    expect(calls).toBe(1);
   });
 
   it('requests the next older page by skipping already loaded latest events', () => {
diff --git a/src/hooks/useSessionLifecycle.ts b/src/hooks/useSessionLifecycle.ts
index f745382..2751141 100644
--- a/src/hooks/useSessionLifecycle.ts
+++ b/src/hooks/useSessionLifecycle.ts
@@ -7,9 +7,11 @@ import { useBootstrapStore } from '../stores/bootstrap.js';
 import { CancelledError } from '../api/client.js';
 import {
   eventHasTerminalRunStatus,
+  maxSeqIdFromEvents,
   sessionEventRunStatus,
 } from '../utils/session-events.js';
 import { mapBackendMessages } from '../utils/messages.js';
+import { rebuildPersistedSessionHistory } from '../utils/persisted-session-history.js';
 import { useStreamingStore } from '../stores/streaming.js';
 import { shouldRenderFeedbackControls, normalizeFeedback } from '../utils/feedback.js';
 import { readPersistedSessionId, resolveSessionToRestore } from '../utils/session.js';
@@ -20,12 +22,16 @@ import type { UiCapabilities } from '../types/capabilities.js';
 import type { ApiFacade } from '../core/api/types.js';
 import { dispatchRunEventToStores } from '../core/run/dispatcher.js';
 import { parseSseChunk, splitSseBuffer } from '../core/transport/sse-parser.js';
-import { createSessionEventCursor } from '../utils/session-event-history.js';
+import {
+  createSessionEventCursor,
+  loadCompleteSessionEventHistory,
+} from '../utils/session-event-history.js';
 import { ingestSessionEventRecord } from '../core/interaction/index.js';
 
 const RESTORE_RECONNECT_DELAY_MS = 500;
 const SESSION_LIST_PAGE_SIZE = 30;
 const SESSION_MESSAGES_PAGE_SIZE = 50;
+const SESSION_EVENTS_PAGE_SIZE = 500;
 const EMPTY_STATUS_RECOVERY_WINDOW_MS = 30 * 60 * 1000;
 
 function waitForRestoreRetry(signal: AbortSignal): Promise<void> {
@@ -111,6 +117,7 @@ export function useSessionLifecycle(ctx: SessionLifecycleContext) {
   const sessionEventCursorRef = useRef(createSessionEventCursor());
   const loadSessionGenerationRef = useRef(0);
   const olderMessageRequestRef = useRef(new Map<string, symbol>());
+  const canonicalRunIdsBySessionRef = useRef(new Map<string, Set<string>>());
   const loadSessionRef = useRef<((sessionId: string) => Promise<void>) | null>(null);
   const fetchSessionsRef = useRef<
     ((
@@ -390,27 +397,51 @@ export function useSessionLifecycle(ctx: SessionLifecycleContext) {
         if (!isStillCurrentSession()) {
           return;
         }
-        const history = mapBackendMessages(messagesData.Messages);
-        useMessageStore.getState().setMessages(history);
-        useSessionStore.getState().setSessionMessageHistory(sessionId, {
-          nextCursor: messagesData.NextCursor,
-          hasMore: messagesData.HasMore,
-        });
-        void loadFeedbackForMessages(agentIdRef.current, sessionId, history);
-        const lastSeqId = messagesData.LatestSeqId || 0;
-
-        // Replay recent durable SessionEvents to restore pending
-        // Interaction/v1 records (refresh / replay never re-submits).
+        const fallbackHistory = mapBackendMessages(messagesData.Messages) as Message[];
+        let history = fallbackHistory;
+        let latestEventSeqId = 0;
+        let canonicalRunIds: string[] = [];
+
+        // RuntimeEvent/v2 is the transcript source of truth. Persisted
+        // ListSessionMessages rows are cumulative snapshots and therefore only
+        // a compatibility fallback for runs without canonical item identity.
         try {
-          const eventsData = await api.listSessionEvents(sessionId, { limit: 50 });
-          if (isStillCurrentSession()) {
-            for (const record of (eventsData.Events || []) as unknown[]) {
+          const eventHistory = await loadCompleteSessionEventHistory(
+            sessionId,
+            (targetSessionId, opts) => api.listSessionEvents(targetSessionId, opts),
+            {
+              pageSize: SESSION_EVENTS_PAGE_SIZE,
+              shouldContinue: isStillCurrentSession,
+            },
+          );
+          if (!isStillCurrentSession()) return;
+          if (eventHistory) {
+            latestEventSeqId = maxSeqIdFromEvents(eventHistory.events);
+            const rebuilt = rebuildPersistedSessionHistory(
+              fallbackHistory,
+              eventHistory.events,
+              sessionId,
+            );
+            canonicalRunIds = rebuilt.canonicalRunIds;
+            if (canonicalRunIds.length > 0) {
+              history = rebuilt.messages;
+            }
+            for (const record of eventHistory.events) {
               ingestSessionEventRecord(record, sessionId);
             }
           }
         } catch (error) {
-          console.warn('[SessionLifecycle] interaction history replay failed:', error);
+          console.warn('[SessionLifecycle] canonical history replay failed:', error);
         }
+        if (!isStillCurrentSession()) return;
+        canonicalRunIdsBySessionRef.current.set(sessionId, new Set(canonicalRunIds));
+        useMessageStore.getState().setMessages(history);
+        useSessionStore.getState().setSessionMessageHistory(sessionId, {
+          nextCursor: messagesData.NextCursor,
+          hasMore: messagesData.HasMore,
+        });
+        void loadFeedbackForMessages(agentIdRef.current, sessionId, history);
+        const lastSeqId = Math.max(messagesData.LatestSeqId || 0, latestEventSeqId);
 
         const runtimeCapabilities = useBootstrapStore.getState().capabilities || uiCapabilities;
         if (runtimeCapabilities.RunLifecycle.Enabled && runtimeCapabilities.RunLifecycle.Checkpoints) {
@@ -678,7 +709,9 @@ export function useSessionLifecycle(ctx: SessionLifecycleContext) {
       ) {
         return;
       }
-      const olderMessages = mapBackendMessages(data.Messages);
+      const canonicalRunIds = canonicalRunIdsBySessionRef.current.get(sessionId) || new Set<string>();
+      const olderMessages = (mapBackendMessages(data.Messages) as Message[])
+        .filter((message) => !message.invocationId || !canonicalRunIds.has(message.invocationId));
       const olderIds = new Set(olderMessages.map((message) => message.id));
       const mergedHistory = [
         ...olderMessages,
diff --git a/src/utils/persisted-session-history.ts b/src/utils/persisted-session-history.ts
new file mode 100644
index 0000000..8149d42
--- /dev/null
+++ b/src/utils/persisted-session-history.ts
@@ -0,0 +1,167 @@
+import type { Message } from '../components/chat/types.js';
+import { buildBlocksFromHistory } from '../core/run/blocks.js';
+import {
+  KernelRunEventTranslator,
+  type KernelSessionEventFrame,
+} from '../core/stream/kernel-events.js';
+import type { SessionEventRecord } from '../types/session-events.js';
+import { buildMessagesFromSessionEvents } from './session-events.js';
+
+type PersistedSessionEventRecord = SessionEventRecord & {
+  Content?: SessionEventRecord['Content'] & {
+    runtime_event?: Record<string, unknown>;
+    session_event?: Record<string, unknown>;
+  };
+};
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function eventTimestamp(value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  const parsed = Date.parse(String(value || ''));
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}
+
+/**
+ * Extract the canonical RuntimeEvent/v2 frame persisted inside a
+ * ListSessionEvents record. The server stores both the SessionEvent envelope
+ * and a flattened runtime_event projection; the latter already carries the
+ * unified Session seq used by replay cursors.
+ */
+export function persistedRuntimeFrame(
+  raw: PersistedSessionEventRecord,
+): KernelSessionEventFrame | null {
+  const runtimeEvent = record(raw?.Content?.runtime_event);
+  if (runtimeEvent && String(runtimeEvent.event_type || '')) {
+    return {
+      ...runtimeEvent,
+      family: 'runtime',
+      seq: Number(raw.SeqId || runtimeEvent.seq || 0),
+      timestamp: raw.Timestamp || runtimeEvent.timestamp,
+    };
+  }
+
+  const envelope = record(raw?.Content?.session_event);
+  if (!envelope || String(envelope.family || '') !== 'runtime') return null;
+  const payload = record(envelope.payload);
+  if (!payload || !String(payload.event_type || envelope.event_type || '')) return null;
+  return {
+    ...payload,
+    family: 'runtime',
+    event_type: payload.event_type || envelope.event_type,
+    run_id: payload.run_id || envelope.run_id,
+    seq: Number(raw.SeqId || envelope.seq || payload.seq || 0),
+    timestamp: raw.Timestamp || envelope.timestamp || payload.timestamp,
+  };
+}
+
+function withHistoryBlocks(message: Message): Message {
+  if (message.role !== 'model') return message;
+  return {
+    ...message,
+    blocks: buildBlocksFromHistory({
+      content: message.content,
+      reasoning: message.reasoning,
+      tools: message.tools,
+    }),
+  };
+}
+
+function enrichCanonicalRun(
+  canonical: Message[],
+  fallback: Message[],
+): Message[] {
+  const fallbackUser = fallback.find((message) => message.role === 'user');
+  const fallbackModels = fallback.filter((message) => message.role === 'model');
+  const canonicalModels = canonical.filter((message) => message.role === 'model');
+  const lastCanonicalModel = canonicalModels.at(-1);
+  const lastFallbackModel = fallbackModels.at(-1);
+
+  return canonical.map((message) => {
+    if (message.role === 'user' && fallbackUser) {
+      return {
+        ...message,
+        ...fallbackUser,
+        invocationId: message.invocationId || fallbackUser.invocationId,
+      };
+    }
+    if (message === lastCanonicalModel && lastFallbackModel) {
+      return withHistoryBlocks({
+        ...message,
+        responseId: lastFallbackModel.responseId || message.responseId,
+        traceId: lastFallbackModel.traceId || message.traceId,
+        rootSpanId: lastFallbackModel.rootSpanId || message.rootSpanId,
+      });
+    }
+    return withHistoryBlocks(message);
+  });
+}
+
+/**
+ * Rebuild the transcript for runs that have canonical RuntimeEvent/v2
+ * history. Cumulative ListSessionMessages rows remain only a compatibility
+ * fallback for legacy runs; they never co-own a canonical run.
+ */
+export function rebuildPersistedSessionHistory(
+  fallbackMessages: Message[],
+  records: PersistedSessionEventRecord[],
+  sessionId: string,
+): {
+  messages: Message[];
+  canonicalRunIds: string[];
+  translatedEvents: SessionEventRecord[];
+} {
+  const translator = new KernelRunEventTranslator(sessionId);
+  const translatedEvents: SessionEventRecord[] = [];
+  const canonicalRunIds = new Set<string>();
+
+  const orderedRecords = [...(records || [])].sort(
+    (left, right) => Number(left.SeqId || 0) - Number(right.SeqId || 0),
+  );
+  for (const persisted of orderedRecords) {
+    const frame = persistedRuntimeFrame(persisted);
+    if (!frame) continue;
+    const runId = String(frame.run_id || '').trim();
+    if (runId) canonicalRunIds.add(runId);
+    const translated = translator.translate(frame);
+    if (!translated) continue;
+    translatedEvents.push({
+      ...translated,
+      SeqId: Number(persisted.SeqId || translated.SeqId || 0),
+      Timestamp: eventTimestamp(persisted.Timestamp || translated.Timestamp),
+    } as SessionEventRecord);
+  }
+
+  const projected = (buildMessagesFromSessionEvents(translatedEvents) as Message[])
+    .filter((message) => message.invocationId && canonicalRunIds.has(message.invocationId));
+  const projectedRunIds = new Set(projected.map((message) => String(message.invocationId || '')));
+  const fallbackByRun = new Map<string, Message[]>();
+  for (const message of fallbackMessages) {
+    const runId = String(message.invocationId || '');
+    if (!runId) continue;
+    fallbackByRun.set(runId, [...(fallbackByRun.get(runId) || []), message]);
+  }
+
+  const canonicalMessages = [...projectedRunIds].flatMap((runId) => enrichCanonicalRun(
+    projected.filter((message) => message.invocationId === runId),
+    fallbackByRun.get(runId) || [],
+  ));
+  const retainedFallback = fallbackMessages.filter((message) => (
+    message.role === 'a2ui'
+    || !message.invocationId
+    || !projectedRunIds.has(message.invocationId)
+  ));
+  const messages = [...retainedFallback, ...canonicalMessages].sort(
+    (left, right) => Number(left.timestamp || 0) - Number(right.timestamp || 0),
+  );
+
+  return {
+    messages,
+    canonicalRunIds: [...projectedRunIds],
+    translatedEvents,
+  };
+}
diff --git a/src/utils/session-event-history.ts b/src/utils/session-event-history.ts
index da019e8..f11fcee 100644
--- a/src/utils/session-event-history.ts
+++ b/src/utils/session-event-history.ts
@@ -45,32 +45,20 @@ export async function loadCompleteSessionEventHistory(
   const shouldContinue = options?.shouldContinue || (() => true);
   const shouldAbort = () => !shouldContinue();
 
-  const probe = await listSessionEvents(sessionId, { offset: 0, limit: 1 });
+  const first = await listSessionEvents(sessionId, { offset: 0, limit: pageSize });
   if (shouldAbort()) return null;
 
-  const total = Math.max(0, Number(probe.Total ?? probe.Events?.length ?? 0) || 0);
-  if (total <= 1) {
+  const total = Math.max(0, Number(first.Total ?? first.Events?.length ?? 0) || 0);
+  if (total <= (first.Events?.length ?? 0)) {
     return {
-      events: ((probe.Events || []) as SessionEventRecord[]),
+      events: ((first.Events || []) as SessionEventRecord[]),
       total,
-      offset: Number(probe.Offset ?? 0),
-      limit: Number(probe.Limit ?? probe.Events?.length ?? 0),
+      offset: Number(first.Offset ?? 0),
+      limit: Number(first.Limit ?? first.Events?.length ?? 0),
     };
   }
 
-  const tailPage = resolveOlderSessionEventPage({ offset: 0, total }, pageSize);
-  if (!tailPage) {
-    return {
-      events: [],
-      total,
-      offset: 0,
-      limit: 0,
-    };
-  }
-  const tail = await listSessionEvents(sessionId, tailPage);
-  if (shouldAbort()) return null;
-
-  let merged = (tail.Events || []) as SessionEventRecord[];
+  let merged = (first.Events || []) as SessionEventRecord[];
   let loadedCount = merged.length;
 
   while (loadedCount < total) {

From e07a98fdd7e431de83f2bc13d1642ce2beda7dd5 Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 21:37:45 +0800
Subject: [PATCH 16/25] chore(release): refresh ksadk-web 0.3.4 provenance

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index c5f37f3..d8b98d7 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "905a146e9a75614c5624d190e89ee3dc5103a41c",
+  "source_commit": "6f6c50222abe7bdc61706dd4d32e8a0108b687f6",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From f4e2396f916f0e2fd89e4f7892b20b7f8e45e236 Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 23:16:17 +0800
Subject: [PATCH 17/25] fix(chat): keep persisted runtime history in canonical
 order

---
 .../persisted-session-history.test.ts         | 41 +++++++++++++++++++
 src/public/conversation.ts                    | 14 +++++++
 src/utils/persisted-session-history.ts        |  9 +++-
 3 files changed, 62 insertions(+), 2 deletions(-)
 create mode 100644 src/__tests__/persisted-session-history.test.ts

diff --git a/src/__tests__/persisted-session-history.test.ts b/src/__tests__/persisted-session-history.test.ts
new file mode 100644
index 0000000..5b19a41
--- /dev/null
+++ b/src/__tests__/persisted-session-history.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { rebuildPersistedSessionHistory } from '../utils/persisted-session-history.js';
+import type { Message } from '../components/chat/types.js';
+import type { PersistedSessionEventRecord } from '../utils/persisted-session-history.js';
+
+describe('rebuildPersistedSessionHistory', () => {
+  it('normalises RuntimeEvent Unix seconds before ordering with millisecond message rows', () => {
+    const fallback: Message[] = [{
+      id: 'user-1',
+      role: 'user',
+      content: '先提问',
+      timestamp: 1_700_000_000_000,
+    }];
+    const events: PersistedSessionEventRecord[] = [{
+      SeqId: 1,
+      EventId: 'event-1',
+      EventType: 'runtime.item.completed',
+      InvocationId: 'run-1',
+      // Production RuntimeEvent/v2 persists this value in Unix seconds.
+      Timestamp: 1_700_000_001 as unknown as string,
+      Content: {
+        runtime_event: {
+          family: 'runtime',
+          event_type: 'item.completed',
+          event_id: 'event-1',
+          run_id: 'run-1',
+          scope_id: 'run-1',
+          item_id: 'assistant-1',
+          item_kind: 'message',
+          snapshot: { parts: [{ part_id: 'text-1', text: '再回答' }] },
+          source: { metadata: { native_item_kind: 'agentMessage' } },
+        },
+      },
+    }];
+
+    const rebuilt = rebuildPersistedSessionHistory(fallback, events, 'session-1');
+
+    expect(rebuilt.messages.map((message) => message.content)).toEqual(['先提问', '再回答']);
+    expect(rebuilt.messages[1]?.timestamp).toBe(1_700_000_001_000);
+  });
+});
diff --git a/src/public/conversation.ts b/src/public/conversation.ts
index 5f7184f..d7fb2b2 100644
--- a/src/public/conversation.ts
+++ b/src/public/conversation.ts
@@ -20,6 +20,20 @@ export {
   createTrustedRendererCatalog,
   surfacePermitsInput,
 } from '../core/conversation/index.js';
+export {
+  persistedRuntimeFrame,
+  rebuildPersistedSessionHistory,
+} from '../utils/persisted-session-history.js';
+export type {
+  PersistedSessionEventRecord,
+} from '../utils/persisted-session-history.js';
+export type {
+  BlockStatus,
+  ProcessingBlock,
+  TextBlock,
+  ThinkingBlock,
+  ToolBlock,
+} from '../core/run/blocks.js';
 export type {
   ConversationArtifact,
   ConversationCapability,
diff --git a/src/utils/persisted-session-history.ts b/src/utils/persisted-session-history.ts
index 8149d42..79346e1 100644
--- a/src/utils/persisted-session-history.ts
+++ b/src/utils/persisted-session-history.ts
@@ -7,7 +7,7 @@ import {
 import type { SessionEventRecord } from '../types/session-events.js';
 import { buildMessagesFromSessionEvents } from './session-events.js';
 
-type PersistedSessionEventRecord = SessionEventRecord & {
+export type PersistedSessionEventRecord = SessionEventRecord & {
   Content?: SessionEventRecord['Content'] & {
     runtime_event?: Record<string, unknown>;
     session_event?: Record<string, unknown>;
@@ -21,7 +21,12 @@ function record(value: unknown): Record<string, unknown> | null {
 }
 
 function eventTimestamp(value: unknown): number {
-  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    // RuntimeEvent/v2 timestamps are Unix seconds while the legacy message
+    // projection and JavaScript Date APIs use milliseconds. Normalise before
+    // sorting or a refreshed run places every user row after all model items.
+    return value > 0 && value < 100_000_000_000 ? value * 1000 : value;
+  }
   const parsed = Date.parse(String(value || ''));
   return Number.isFinite(parsed) ? parsed : Date.now();
 }

From 520c31cfd6d6181f514e3e30de2e181ca9b3454f Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Mon, 31 Aug 2026 23:16:38 +0800
Subject: [PATCH 18/25] chore(release): refresh ksadk-web 0.3.4 provenance

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index d8b98d7..28caf68 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "6f6c50222abe7bdc61706dd4d32e8a0108b687f6",
+  "source_commit": "f4e2396f916f0e2fd89e4f7892b20b7f8e45e236",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From afbce007afde15e3ef47e7ac3933a0874f5b282c Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Tue, 1 Sep 2026 00:09:49 +0800
Subject: [PATCH 19/25] fix(stream): reject empty successful responses

---
 src/__tests__/run-engine.test.ts | 12 ++++++++++++
 src/core/run/engine.ts           |  6 ++++++
 2 files changed, 18 insertions(+)

diff --git a/src/__tests__/run-engine.test.ts b/src/__tests__/run-engine.test.ts
index b7edb8f..4e1cea8 100644
--- a/src/__tests__/run-engine.test.ts
+++ b/src/__tests__/run-engine.test.ts
@@ -1335,6 +1335,10 @@ describe('RunEngineImpl', () => {
       },
     });
     const settledSessionIds: Array<string | null> = [];
+    const events: Array<{ type: string; error?: Error }> = [];
+    engine.subscribe((event) => {
+      events.push(event);
+    });
 
     engine.updateConfig({
       agentId: 'agent-live',
@@ -1362,6 +1366,8 @@ describe('RunEngineImpl', () => {
     expect(calls[0]).toMatchObject({ SessionId: 'session-history' });
     expect(createdSessions).toEqual([]);
     expect(settledSessionIds).toEqual(['session-history']);
+    expect(events.some((event) => event.type === 'activity' && 'phase' in event && event.phase === '运行完成')).toBe(false);
+    expect(events.find((event) => event.type === 'error')?.error?.message).toContain('空响应流');
   });
 
   it('does not create a second session or replay a prompt after an empty first stream', async () => {
@@ -1383,6 +1389,10 @@ describe('RunEngineImpl', () => {
         });
       },
     });
+    const events: Array<{ type: string; error?: Error }> = [];
+    engine.subscribe((event) => {
+      events.push(event);
+    });
 
     engine.updateConfig({
       agentId: 'agent-live',
@@ -1399,6 +1409,8 @@ describe('RunEngineImpl', () => {
     expect(createdSessions).toEqual(['session-1']);
     expect(calls).toHaveLength(1);
     expect(calls[0]).toMatchObject({ SessionId: 'session-1' });
+    expect(events.some((event) => event.type === 'activity' && 'phase' in event && event.phase === '运行完成')).toBe(false);
+    expect(events.find((event) => event.type === 'error')?.error?.message).toContain('空响应流');
   });
 
   it('keeps response.failed as failed instead of overwriting it as completed', async () => {
diff --git a/src/core/run/engine.ts b/src/core/run/engine.ts
index 9952f20..fe3a56c 100644
--- a/src/core/run/engine.ts
+++ b/src/core/run/engine.ts
@@ -1188,11 +1188,13 @@ export class RunEngineImpl implements RunEngine {
     const decoder = new TextDecoder();
     let buffer = '';
     let messageCreated = false;
+    let receivedByteCount = 0;
 
     try {
       while (true) {
         const { value, done } = await reader.read();
         if (done) break;
+        receivedByteCount += value.byteLength;
         if (!messageCreated) {
           messageCreated = true;
           this.emit({ type: 'assistant_message_created', messageId, invocationId });
@@ -1256,6 +1258,10 @@ export class RunEngineImpl implements RunEngine {
       }
     }
 
+    if (receivedByteCount === 0) {
+      throw new Error('运行时返回了空响应流，请稍后重试；若问题持续，请检查运行时状态。');
+    }
+
     return {};
   }
 

From 88412e1e2e08171a410863d55b4600d546dd9bca Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Tue, 1 Sep 2026 00:10:00 +0800
Subject: [PATCH 20/25] chore(release): refresh ksadk-web 0.3.4 provenance

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index 28caf68..36ffd95 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "f4e2396f916f0e2fd89e4f7892b20b7f8e45e236",
+  "source_commit": "afbce007afde15e3ef47e7ac3933a0874f5b282c",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From 670887a15fd7fce0e40c02d0754da32e406e5b05 Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Tue, 1 Sep 2026 01:19:32 +0800
Subject: [PATCH 21/25] fix(chat): retain fallback for incomplete runtime
 replay

---
 .../persisted-session-history.test.ts         | 56 +++++++++++++++++++
 src/utils/persisted-session-history.ts        | 31 ++++++++--
 2 files changed, 83 insertions(+), 4 deletions(-)

diff --git a/src/__tests__/persisted-session-history.test.ts b/src/__tests__/persisted-session-history.test.ts
index 5b19a41..c12d554 100644
--- a/src/__tests__/persisted-session-history.test.ts
+++ b/src/__tests__/persisted-session-history.test.ts
@@ -38,4 +38,60 @@ describe('rebuildPersistedSessionHistory', () => {
     expect(rebuilt.messages.map((message) => message.content)).toEqual(['先提问', '再回答']);
     expect(rebuilt.messages[1]?.timestamp).toBe(1_700_000_001_000);
   });
+
+  it('keeps the compatibility projection when canonical history contains only a user item', () => {
+    const fallback: Message[] = [
+      {
+        id: 'user-fallback',
+        role: 'user',
+        content: '继续上文',
+        timestamp: 1_700_000_000_000,
+        invocationId: 'run-incomplete',
+      },
+      {
+        id: 'assistant-fallback',
+        role: 'model',
+        content: '这是仍可从兼容投影读取的回复。',
+        timestamp: 1_700_000_001_000,
+        invocationId: 'run-incomplete',
+      },
+    ];
+    const events: PersistedSessionEventRecord[] = [{
+      SeqId: 1,
+      EventId: 'event-user-only',
+      EventType: 'runtime.item.completed',
+      InvocationId: 'run-incomplete',
+      Timestamp: 1_700_000_000 as unknown as string,
+      Content: {
+        runtime_event: {
+          family: 'runtime',
+          event_type: 'item.completed',
+          event_id: 'event-user-only',
+          run_id: 'run-incomplete',
+          scope_id: 'run-incomplete',
+          item_id: 'user-item',
+          item_kind: 'message',
+          snapshot: {
+            parts: [{
+              part_id: 'user-part',
+              content_type: 'data',
+              data: {
+                type: 'userMessage',
+                content: [{ type: 'text', text: '继续上文' }],
+              },
+            }],
+          },
+          source: { metadata: { native_item_kind: 'userMessage' } },
+        },
+      },
+    }];
+
+    const rebuilt = rebuildPersistedSessionHistory(fallback, events, 'session-1');
+
+    expect(rebuilt.messages.map((message) => message.content)).toEqual([
+      '继续上文',
+      '这是仍可从兼容投影读取的回复。',
+    ]);
+    expect(rebuilt.canonicalRunIds).toEqual([]);
+  });
 });
diff --git a/src/utils/persisted-session-history.ts b/src/utils/persisted-session-history.ts
index 79346e1..d51e43e 100644
--- a/src/utils/persisted-session-history.ts
+++ b/src/utils/persisted-session-history.ts
@@ -106,6 +106,26 @@ function enrichCanonicalRun(
   });
 }
 
+/**
+ * A RuntimeEvent/v2 run only replaces the compatibility projection once its
+ * terminal assistant output is present. A user item, run transition, or an
+ * open stream snapshot alone proves that the run exists, but does not prove
+ * that replay can render its reply. Treating that partial evidence as
+ * authoritative used to erase a persisted assistant message after refresh.
+ */
+function completedCanonicalRunIds(messages: Message[]): Set<string> {
+  return new Set(
+    messages
+      .filter((message) => (
+        message.role === 'model'
+        && message.eventType === 'assistant_message'
+        && Boolean(String(message.content || '').trim())
+        && Boolean(message.invocationId)
+      ))
+      .map((message) => String(message.invocationId)),
+  );
+}
+
 /**
  * Rebuild the transcript for runs that have canonical RuntimeEvent/v2
  * history. Cumulative ListSessionMessages rows remain only a compatibility
@@ -143,7 +163,6 @@ export function rebuildPersistedSessionHistory(
 
   const projected = (buildMessagesFromSessionEvents(translatedEvents) as Message[])
     .filter((message) => message.invocationId && canonicalRunIds.has(message.invocationId));
-  const projectedRunIds = new Set(projected.map((message) => String(message.invocationId || '')));
   const fallbackByRun = new Map<string, Message[]>();
   for (const message of fallbackMessages) {
     const runId = String(message.invocationId || '');
@@ -151,14 +170,18 @@ export function rebuildPersistedSessionHistory(
     fallbackByRun.set(runId, [...(fallbackByRun.get(runId) || []), message]);
   }
 
-  const canonicalMessages = [...projectedRunIds].flatMap((runId) => enrichCanonicalRun(
+  // A partially persisted canonical run must never make the older Server
+  // projection disappear. This matters during upgrade: a historical runtime
+  // may have written the user item but not a terminal agentMessage item.
+  const completeCanonicalRunIds = completedCanonicalRunIds(projected);
+  const canonicalMessages = [...completeCanonicalRunIds].flatMap((runId) => enrichCanonicalRun(
     projected.filter((message) => message.invocationId === runId),
     fallbackByRun.get(runId) || [],
   ));
   const retainedFallback = fallbackMessages.filter((message) => (
     message.role === 'a2ui'
     || !message.invocationId
-    || !projectedRunIds.has(message.invocationId)
+    || !completeCanonicalRunIds.has(message.invocationId)
   ));
   const messages = [...retainedFallback, ...canonicalMessages].sort(
     (left, right) => Number(left.timestamp || 0) - Number(right.timestamp || 0),
@@ -166,7 +189,7 @@ export function rebuildPersistedSessionHistory(
 
   return {
     messages,
-    canonicalRunIds: [...projectedRunIds],
+    canonicalRunIds: [...completeCanonicalRunIds],
     translatedEvents,
   };
 }

From 255972d639d4170e27c22175de0d72e7c67dd38a Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Tue, 1 Sep 2026 07:31:16 +0800
Subject: [PATCH 22/25] fix(conversation): isolate terminal state by run

---
 src/__tests__/hosted-conversation.test.ts | 51 +++++++++++++++++++++++
 src/__tests__/run-engine.test.ts          | 36 ++++++++++++++++
 src/core/conversation/hosted.ts           |  6 +++
 src/core/run/dispatcher.ts                |  9 +++-
 src/core/run/engine.ts                    |  2 +-
 src/core/run/types.ts                     |  2 +-
 6 files changed, 103 insertions(+), 3 deletions(-)

diff --git a/src/__tests__/hosted-conversation.test.ts b/src/__tests__/hosted-conversation.test.ts
index 6e4a22b..25e2e62 100644
--- a/src/__tests__/hosted-conversation.test.ts
+++ b/src/__tests__/hosted-conversation.test.ts
@@ -63,6 +63,57 @@ function stream(body: string): Response {
 }
 
 describe('Hosted UI canonical ConversationItem projection', () => {
+  it('keeps the visible fallback when an interim canonical snapshot has no renderable item', async () => {
+    const client = new HttpConversationClient({
+      fetch: vi.fn(async () => stream([
+        frame(1, item(
+          'progress-only',
+          'progress-event',
+          'progress',
+          'conversation.item.progress/v1',
+          { status: 'running' },
+        )),
+        frame(2, item(
+          'progress-terminal',
+          'progress-terminal-event',
+          'progress',
+          'conversation.item.progress/v1',
+          { status: 'completed' },
+          { operation: 'completed', lifecycle: 'completed' },
+        )),
+      ].join(''))),
+      maxReconnects: 0,
+    });
+    useSessionStore.getState().setCurrentSessionId('session-hosted');
+    useMessageStore.getState().setMessages([{
+      id: 'legacy-preview',
+      role: 'model',
+      content: 'foreground preview remains visible',
+      timestamp: 1,
+      invocationId: 'run-hosted',
+    }]);
+
+    await client.streamTurn({
+      bootstrap: { buildId: 'build-hosted', surface: SURFACE },
+      input: buildConversationInput({
+        inputId: 'input-progress-only',
+        sessionId: 'session-hosted',
+        idempotencyKey: 'turn-progress-only',
+        parts: [{ kind: 'text', text: 'hello' }],
+      }),
+      onUpdate: (snapshot) => dispatchRunEventToStores({
+        type: 'conversation_snapshot',
+        result: snapshot,
+        sessionId: 'session-hosted',
+      }),
+    });
+
+    expect(useMessageStore.getState().messages).toContainEqual(expect.objectContaining({
+      id: 'legacy-preview',
+      content: 'foreground preview remains visible',
+    }));
+  });
+
   it('uses one identity reducer across reconnect for text, reasoning, tool, approval and A2UI', async () => {
     const operations = [{
       version: 'v0.9',
diff --git a/src/__tests__/run-engine.test.ts b/src/__tests__/run-engine.test.ts
index 4e1cea8..400e7cf 100644
--- a/src/__tests__/run-engine.test.ts
+++ b/src/__tests__/run-engine.test.ts
@@ -1121,6 +1121,42 @@ describe('RunEngineImpl', () => {
     });
   });
 
+  it('only finalizes streaming blocks owned by the completed canonical run', () => {
+    useSessionStore.getState().setCurrentSessionId('session-live');
+    useMessageStore.getState().setMessages([
+      {
+        id: 'assistant-run-a',
+        role: 'model',
+        content: '',
+        timestamp: 1,
+        runId: 'run-a',
+        blocks: [
+          { id: 'thinking-a', type: 'thinking', content: 'run a is thinking', status: 'streaming' },
+        ],
+      },
+      {
+        id: 'assistant-run-b',
+        role: 'model',
+        content: '',
+        timestamp: 2,
+        runId: 'run-b',
+        blocks: [
+          { id: 'thinking-b', type: 'thinking', content: 'run b is thinking', status: 'streaming' },
+        ],
+      },
+    ]);
+
+    dispatchRunEventToStores({
+      type: 'stream_ended',
+      sessionId: 'session-live',
+      runId: 'run-a',
+    });
+
+    const [runA, runB] = useMessageStore.getState().messages;
+    expect(runA.blocks?.[0]?.status).toBe('done');
+    expect(runB.blocks?.[0]?.status).toBe('streaming');
+  });
+
   it('settles running tools when a run reaches a terminal status', () => {
     useSessionStore.getState().setCurrentSessionId('session-live');
     dispatchRunEventToStores({
diff --git a/src/core/conversation/hosted.ts b/src/core/conversation/hosted.ts
index 5fc37cd..d39b804 100644
--- a/src/core/conversation/hosted.ts
+++ b/src/core/conversation/hosted.ts
@@ -355,6 +355,12 @@ export function mergeConversationRunMessages(
   result: ConversationStreamResult,
 ): Message[] {
   const projected = projectConversationStreamForHostedUi(result).messages;
+  // A reducer snapshot is allowed to contain only hidden progress or an
+  // extension that this renderer intentionally does not expose.  Such a
+  // snapshot is not a transcript replacement.  Removing the legacy preview
+  // here used to produce the brief blank screen seen during slow/reordered
+  // cloud streams.
+  if (!projected.length) return previous;
   const belongsToRun = (message: Message) => (
     (message.eventType === EVENT_TYPE && message.runId === result.runId)
     || message.invocationId === result.runId
diff --git a/src/core/run/dispatcher.ts b/src/core/run/dispatcher.ts
index 3da305b..f82eef8 100644
--- a/src/core/run/dispatcher.ts
+++ b/src/core/run/dispatcher.ts
@@ -383,7 +383,14 @@ export function dispatchRunEventToStores(event: RunEvent) {
       if (!sessionIsOffscreen) {
         useMessageStore.getState().patchMessages((prev) =>
           prev.map((msg) => {
-            if (msg.role !== 'model' || !msg.blocks?.some((b) => b.status === 'streaming')) {
+            const belongsToEndedRun = !event.runId
+              || msg.runId === event.runId
+              || msg.invocationId === event.runId;
+            if (
+              !belongsToEndedRun
+              || msg.role !== 'model'
+              || !msg.blocks?.some((b) => b.status === 'streaming')
+            ) {
               return msg;
             }
             return {
diff --git a/src/core/run/engine.ts b/src/core/run/engine.ts
index fe3a56c..ffcfbf2 100644
--- a/src/core/run/engine.ts
+++ b/src/core/run/engine.ts
@@ -341,7 +341,7 @@ export class RunEngineImpl implements RunEngine {
             status: 'completed',
             countEvent: false,
           });
-          this.emit({ type: 'stream_ended' });
+          this.emit({ type: 'stream_ended', sessionId, runId: result.runId });
           return;
         }
 
diff --git a/src/core/run/types.ts b/src/core/run/types.ts
index 4657ef2..5741955 100644
--- a/src/core/run/types.ts
+++ b/src/core/run/types.ts
@@ -61,7 +61,7 @@ export type RunEvent =
     }
   | { type: 'compaction'; phase: string; trigger?: string; compactedUntilSeqId?: number; sessionId?: string | null }
   | { type: 'system_message'; content: string; sessionId?: string | null }
-  | { type: 'stream_ended'; sessionId?: string | null }
+  | { type: 'stream_ended'; sessionId?: string | null; runId?: string | null }
   | { type: 'error'; error: Error; sessionId?: string | null }
   | { type: 'rate_limited'; retryAfterSec?: number; message?: string; sessionId?: string | null }
   | { type: 'terminal'; status: string; sessionId?: string | null }

From a46a43737f377d6cc40a9e57af7500efa3939865 Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Tue, 1 Sep 2026 07:31:48 +0800
Subject: [PATCH 23/25] chore(release): attest ksadk-web 0.3.4 stream fix

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index 36ffd95..ccef438 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "afbce007afde15e3ef47e7ac3933a0874f5b282c",
+  "source_commit": "255972d639d4170e27c22175de0d72e7c67dd38a",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

From 5a23f235b31600fb44f4f939de3e60d0e76056df Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Tue, 1 Sep 2026 10:22:05 +0800
Subject: [PATCH 24/25] fix(stream): separate mirrored legacy answer from
 reasoning

---
 CHANGELOG.md                     |  6 ++++++
 src/__tests__/run-engine.test.ts | 21 +++++++++++++++++++++
 src/core/run/blocks.ts           | 25 +++++++++++++++++++++++++
 src/core/run/dispatcher.ts       | 25 ++++++++++++++++++++-----
 4 files changed, 72 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bee7f3c..2deac80 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,12 @@
   separate answer. Canonical runs retain item identity across reload, while
   historical runtimes without canonical events continue to use the projected
   message API as a compatibility fallback.
+- Repair the legacy runtime shape that streamed an answer through the
+  reasoning channel and repeated it as a terminal snapshot. When no text
+  delta was received and the exact terminal answer is mirrored only at the
+  tail of the final thinking block, the renderer removes that run-local mirror
+  before presenting the authoritative answer; unrelated or repeated text is
+  never deduplicated by content.
 - Keep a conversation turn active until an explicit run-level terminal status
   arrives. Completed user messages, tools, approvals, usage reports, and
   provider notifications no longer unlock the composer or trigger duplicate
diff --git a/src/__tests__/run-engine.test.ts b/src/__tests__/run-engine.test.ts
index 400e7cf..abfc939 100644
--- a/src/__tests__/run-engine.test.ts
+++ b/src/__tests__/run-engine.test.ts
@@ -1099,6 +1099,27 @@ describe('RunEngineImpl', () => {
     });
   });
 
+  it('removes only a terminal answer mirrored at the tail of legacy reasoning', () => {
+    dispatchRunEventToStores({
+      type: 'reasoning_delta',
+      messageId: 'assistant-legacy',
+      delta: 'I will summarize. 最终答案',
+    });
+    dispatchRunEventToStores({
+      type: 'text_final',
+      messageId: 'assistant-legacy',
+      text: '最终答案',
+    });
+
+    const message = useMessageStore.getState().messages[0];
+    expect(message.reasoning).toBe('I will summarize. ');
+    expect(message.content).toBe('最终答案');
+    expect(message.blocks).toEqual([
+      expect.objectContaining({ type: 'thinking', content: 'I will summarize. ', status: 'done' }),
+      expect.objectContaining({ type: 'text', content: '最终答案', status: 'done' }),
+    ]);
+  });
+
   it('settles an offscreen session when its Responses stream ends after a session switch', () => {
     useSessionStore.getState().setCurrentSessionId('session-visible');
     useStreamingStore.getState().setSessionStreaming('session-background', true);
diff --git a/src/core/run/blocks.ts b/src/core/run/blocks.ts
index 2cfeac0..dc7261a 100644
--- a/src/core/run/blocks.ts
+++ b/src/core/run/blocks.ts
@@ -117,6 +117,31 @@ export function finalizeTextBlock(
   return [...next, { id: nextId('text'), type: 'text', content: text, status: 'done' }];
 }
 
+/**
+ * Compatibility for runtimes that mislabeled a streamed final answer as the
+ * tail of reasoning and only emitted the answer's authoritative snapshot at
+ * completion. This is deliberately narrow: it touches only the last thinking
+ * block and only when that block ends with the exact terminal answer.
+ */
+export function stripMirroredTerminalAnswerFromThinking(
+  blocks: ProcessingBlock[] | undefined,
+  terminalAnswer: string,
+): ProcessingBlock[] {
+  if (!terminalAnswer) return [...(blocks ?? [])];
+  const next = [...(blocks ?? [])];
+  const last = next[next.length - 1];
+  if (last?.type !== 'thinking' || !last.content.endsWith(terminalAnswer)) {
+    return next;
+  }
+  const content = last.content.slice(0, -terminalAnswer.length);
+  if (!content) {
+    next.pop();
+    return next;
+  }
+  next[next.length - 1] = { ...last, content };
+  return next;
+}
+
 /** upsert 工具块(对应 wework mergeProcessingBlock + finalize):
  *  先关闭打开的 thinking 块,再按 toolName 找已有 tool 块更新,否则新建。 */
 export function upsertToolBlock(
diff --git a/src/core/run/dispatcher.ts b/src/core/run/dispatcher.ts
index f82eef8..7b22afa 100644
--- a/src/core/run/dispatcher.ts
+++ b/src/core/run/dispatcher.ts
@@ -4,6 +4,7 @@ import {
   appendTextBlock,
   finalizeTextBlock,
   finalizeThinkingBlocks,
+  stripMirroredTerminalAnswerFromThinking,
   upsertToolBlock,
 } from './blocks.js';
 import { useMessageStore } from '../../stores/message.js';
@@ -145,11 +146,25 @@ export function dispatchRunEventToStores(event: RunEvent) {
       ms.patchMessages((prev) =>
         prev.map((msg) =>
           msg.id === event.messageId
-            ? {
-                ...msg,
-                content: event.text,
-                blocks: finalizeTextBlock(msg.blocks, event.text),
-              }
+            ? (() => {
+                const mirroredLegacyAnswer = Boolean(
+                  event.text
+                  && !msg.content
+                  && msg.reasoning?.endsWith(event.text),
+                );
+                const reasoning = mirroredLegacyAnswer
+                  ? msg.reasoning!.slice(0, -event.text.length)
+                  : msg.reasoning;
+                const blocks = mirroredLegacyAnswer
+                  ? stripMirroredTerminalAnswerFromThinking(msg.blocks, event.text)
+                  : msg.blocks;
+                return {
+                  ...msg,
+                  reasoning,
+                  content: event.text,
+                  blocks: finalizeTextBlock(blocks, event.text),
+                };
+              })()
             : msg,
         ),
       );

From 1fbe571ce10f752c1616e82f6a95dffc7ceb9781 Mon Sep 17 00:00:00 2001
From: xiayu <xiayu@kingsoft.com>
Date: Tue, 1 Sep 2026 10:22:35 +0800
Subject: [PATCH 25/25] chore(release): attest final 0.3.4 stream candidate

---
 RELEASE_PROVENANCE.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_PROVENANCE.json b/RELEASE_PROVENANCE.json
index ccef438..0ff66af 100644
--- a/RELEASE_PROVENANCE.json
+++ b/RELEASE_PROVENANCE.json
@@ -2,6 +2,6 @@
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
   "version": "0.3.4",
-  "source_commit": "255972d639d4170e27c22175de0d72e7c67dd38a",
+  "source_commit": "5a23f235b31600fb44f4f939de3e60d0e76056df",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }