feat(web-shell): expose assistant turn settlement lifecycle

docs/design/web-shell/web-shell-assistant-turn-settlement.md

@@ -0,0 +1,54 @@
+# Web Shell Assistant Turn Settlement
+
+## Problem
+
+Embedding hosts currently infer turn completion from Web Shell's rendered
+streaming state. That state is suitable for loading UI, but it does not identify
+the daemon prompt or distinguish completion, cancellation, and failure.
+
+## Contract
+
+`WebShellProps.onAssistantTurnSettled` reports:
+
+- the session id and daemon prompt id;
+- `completed`, `cancelled`, or `failed`;
+- the daemon stop reason when present;
+- the final retained top-level assistant message when available;
+- error details for failed prompts.
+
+The stable host idempotency key is `(sessionId, promptId)`. Existing
+`onSessionChange({ type: 'turn_complete' })` behavior remains unchanged.
+
+## Delivery
+
+Each mounted `DaemonSessionProvider` publishes every prompt terminal observed
+on its live SSE stream after the terminal transcript projection is committed.
+Hosts that need submitter ownership correlate the prompt id with their submit
+result. On reconnect, a terminal carried only by the replay snapshot publishes
+when this provider previously admitted that prompt. That admission gate keeps
+ordinary persisted-history loading silent while surviving session switches and
+epoch-reset reloads that discard the active request controller.
+
+A lost connection or missing terminal does not publish a settlement: neither
+condition proves how the prompt ended. Hosts receive only daemon terminal
+events observed live or through reconnect replay.
+
+The provider suppresses duplicate terminals for its mounted lifetime. A host
+can mount the same session in more than one provider, such as the main chat and
+a Split View pane, so durable cross-provider suppression remains the host's
+responsibility through the documented idempotency key.
+
+The final message is optional because bounded transcript retention, partial
+history, cancellation, and failure can legitimately leave no retained assistant
+text. Artifact and workspace projection have separate lifecycles and are not
+implied to be settled by this callback.
+
+## Verification
+
+- completed, cancelled, and failed live terminals publish once;
+- subscribers observe the terminal transcript projection before the callback;
+- duplicate terminals publish once per provider mount;
+- persisted history load is silent while reconnect catch-up publishes,
+  including a terminal that arrives through the replay snapshot;
+- main chat and Split View providers forward the callback;
+- existing `onSessionChange` behavior is unchanged.

packages/web-shell/README.md

@@ -365,6 +365,7 @@ const projection = projectChatRecordsToDaemonTranscript(records);
 | `onBrandResolved`          | `(brand: WebShellResolvedBrand) => void`                                                                                              | 品牌解析完成后触发，载荷只含 `name` 与 `logoDataUri`（不含 `logo` 节点），供宿主应用到自己的文档；shell 自身从不写 `document.title` 或 favicon |
 | `onSlashCommand`           | `(command: WebShellSlashCommand) => boolean \| void`                                                                                  | 斜杠命令进入默认处理前触发；返回 `true` 时由宿主接管并跳过默认行为                                                                             |
 | `onSessionArtifactsChange` | `(change: WebShellSessionArtifactsChange) => void`                                                                                    | Session Artifact 初始恢复或变化后返回当前完整快照与 turn 投影                                                                                  |
+| `onAssistantTurnSettled`   | `(event: WebShellAssistantTurnSettledEvent) => void`                                                                                  | daemon 权威终态提交后触发；多个 provider 可能重复上报，宿主按 `(sessionId, promptId)` 去重                                                     |
 
 宿主可以监听命令，也可以返回 `true` 接管对应操作：
 

packages/web-shell/client/App.test.tsx

@@ -268,6 +268,7 @@ const {
   mockReleaseWebTerminal,
   mockUseWorkspaceSessionLiveState,
   mockUseDaemonSessionActivityBridge,
+  mockUseDaemonActivePromptBridge,
 } = vi.hoisted(() => {
   const connection: MockConnection = {
     status: 'connected',
@@ -763,6 +764,7 @@ const {
     mockReleaseDetachedWebTerminal: vi.fn(),
     mockUseWorkspaceSessionLiveState: vi.fn(() => new Map()),
     mockUseDaemonSessionActivityBridge: vi.fn(),
+    mockUseDaemonActivePromptBridge: vi.fn(),
   };
 });
 
@@ -1667,6 +1669,7 @@ vi.mock('./session-catalog/session-catalog-hooks', () => ({
     authoritative: true,
   }),
   useDaemonSessionActivityBridge: mockUseDaemonSessionActivityBridge,
+  useDaemonActivePromptBridge: mockUseDaemonActivePromptBridge,
   // The Workspaces overview panel's per-row session counts; inert here.
   useSessionCatalogQuery: () => ({
     page: undefined,
@@ -10327,6 +10330,10 @@ beforeEach(() => {
     hasActivePrompt: testState.sessionHasActivePrompt,
     activeWorkState: undefined,
   }));
+  mockUseDaemonActivePromptBridge.mockReset();
+  mockUseDaemonActivePromptBridge.mockImplementation(
+    () => testState.sessionHasActivePrompt,
+  );
   mockWorkspace.status = 'connected';
   mockWorkspace.brand = undefined;
   mockWorkspace.brandSettled = false;

packages/web-shell/client/App.tsx

@@ -420,8 +420,10 @@ import {
   type WebShellBottomStatusItem,
   type WebShellPreparedSubmit,
   type WebShellSubmitSnapshot,
+  type WebShellAssistantTurnSettledEvent,
   type WebShellSessionArtifactsChange,
 } from './customization';
+import { useAssistantTurnSettlementProjection } from './assistant-turn-settlement';
 import type { CommandDisplayCategoryOrder } from './utils/commandDisplay';
 import { WebShellPortalRootContext } from './portalRoot';
 import { CompactModeContext, TodoContextsProvider } from './WebShellContexts';
@@ -1373,6 +1375,12 @@ export interface WebShellProps {
   composerInputVersion?: number;
   /** Called when a session-level event occurs (rename, submit, turn complete). */
   onSessionChange?: (event: SessionChangeEvent) => void;
+  /**
+   * Called for authoritative terminals observed live, or replayed for a prompt
+   * this provider admitted. Multiple mounted providers can report the same
+   * `(sessionId, promptId)`, so hosts should deduplicate by that key.
+   */
+  onAssistantTurnSettled?: (event: WebShellAssistantTurnSettledEvent) => void;
   /**
    * Prepare the immutable payload for a daemon submission. Called once for a
    * direct or queued logical submit, after local command routing and before
@@ -3059,6 +3067,7 @@ export function App({
   composerInput,
   composerInputVersion,
   onSessionChange,
+  onAssistantTurnSettled,
   prepareSubmit,
   onSubmitBefore,
   restartSseOnPrompt,
@@ -3067,6 +3076,7 @@ export function App({
   lockedWorkspaceCwd,
   lockedWorkspaceCapability,
 }: AppProps = {}) {
+  useAssistantTurnSettlementProjection(onAssistantTurnSettled);
   const [chatWidthMode, setChatWidthMode] =
     useState<ChatWidthMode>(readChatWidthMode);
   const [selectedLanguage, setSelectedLanguage] = useState<WebShellLanguage>(
@@ -18537,6 +18547,7 @@ export function App({
                       <SplitView
                         planControlVisible={visibleComposerToolbarActions.includes('plan')}
                         sessionIds={splitSessionIds}
+                        onAssistantTurnSettled={onAssistantTurnSettled}
                         showSessionDetails={
                           (sidebarOptions.sessionActions?.items ??
                             DEFAULT_SESSION_ACTION_ITEMS).includes('details')

packages/web-shell/client/adapters/transcriptToMessages.ts

@@ -1806,6 +1806,26 @@ export function splitInsightSegments(text: string): InsightSegment[] | null {
   return segments.length > 0 ? segments : null;
 }
 
+/**
+ * The visible assistant text of a block's text, with insight protocol frames
+ * (`insight_progress` / `insight_ready` / `insight_error`) stripped exactly as
+ * `transcriptBlocksToDaemonMessages` strips them. A payload-only block — one
+ * whose only content is such a frame — renders to no assistant text and
+ * therefore yields an empty string, so callers that publish a turn's final
+ * answer can skip it instead of leaking raw protocol JSON.
+ */
+export function assistantVisibleTextOf(text: string): string {
+  const segments = splitInsightSegments(text);
+  if (!segments) return text.trim();
+  return segments
+    .filter(
+      (segment): segment is { kind: 'text'; text: string } =>
+        segment.kind === 'text',
+    )
+    .map((segment) => segment.text)
+    .join(' ');
+}
+
 function inferToolKind(
   toolName?: string,
   toolKind?: string,