@adhdev/daemon-core 0.8.60 → 0.8.62

package/dist/providers/chat-message-normalization.d.ts

@@ -0,0 +1,43 @@
+import type { ChatMessage } from '../types.js';
+export declare const BUILTIN_CHAT_MESSAGE_KINDS: readonly ["standard", "thought", "tool", "terminal", "system"];
+export type BuiltinChatMessageKind = typeof BUILTIN_CHAT_MESSAGE_KINDS[number];
+export type ChatMessageKind = BuiltinChatMessageKind | (string & {});
+export declare function isBuiltinChatMessageKind(kind: unknown): kind is BuiltinChatMessageKind;
+export declare function normalizeChatMessageKind(kind: unknown, role: unknown): ChatMessageKind;
+export declare function buildChatMessage<T extends Omit<ChatMessage, 'kind'> & {
+    kind?: ChatMessageKind;
+}>(message: T): T & {
+    kind: ChatMessageKind;
+};
+export declare function buildSystemChatMessage<T extends Omit<ChatMessage, 'role' | 'kind'> & {
+    role?: 'system';
+    kind?: ChatMessageKind;
+}>(message: T): (T & {
+    role: 'system';
+    kind: ChatMessageKind;
+});
+export declare function buildRuntimeSystemChatMessage<T extends Omit<ChatMessage, 'role' | 'kind' | 'senderName'> & {
+    role?: 'system';
+    kind?: ChatMessageKind;
+    senderName?: string;
+}>(message: T): (T & {
+    role: 'system';
+    kind: ChatMessageKind;
+    senderName: string;
+});
+export declare function buildAssistantChatMessage<T extends Omit<ChatMessage, 'role' | 'kind'> & {
+    role?: 'assistant';
+    kind?: ChatMessageKind;
+}>(message: T): (T & {
+    role: 'assistant';
+    kind: ChatMessageKind;
+});
+export declare function buildUserChatMessage<T extends Omit<ChatMessage, 'role' | 'kind'> & {
+    role?: 'user';
+    kind?: ChatMessageKind;
+}>(message: T): (T & {
+    role: 'user';
+    kind: ChatMessageKind;
+});
+export declare function normalizeChatMessage<T extends ChatMessage>(message: T): T;
+export declare function normalizeChatMessages<T extends ChatMessage>(messages: T[] | null | undefined): T[];

package/dist/providers/cli-provider-instance.d.ts

@@ -89,6 +89,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private formatMarkerTimestamp;
     private maybeAppendRuntimeRecoveryMessage;
     private appendRuntimeSystemMessage;
+    private appendRuntimeMessage;
     private mergeConversationMessages;
     private formatApprovalRequestMessage;
     private promoteProviderSessionId;

package/dist/providers/contracts.d.ts

@@ -7,6 +7,7 @@
  * - User custom providers use the same contracts
  */
 import type { ProviderSummaryMetadata } from '../shared-types.js';
+import type { ChatMessageKind } from './chat-message-normalization.js';
 export interface ReadChatResult {
     messages: ChatMessage[];
     status: AgentStatus;
@@ -43,7 +44,7 @@ export interface ModalInfo {
 export interface ProviderEffectMessage {
     role?: 'system' | 'assistant' | 'user';
     content: string | MessagePart[];
-    kind?: string;
+    kind?: ChatMessageKind;
     senderName?: string;
 }
 export interface ProviderEffectToast {
@@ -59,6 +60,9 @@ export interface ProviderEffectNotification {
     channels?: ProviderNotificationChannel[];
     preferenceKey?: ProviderNotificationPreferenceKey;
     bubbleContent?: string | MessagePart[];
+    bubbleKind?: ChatMessageKind;
+    bubbleRole?: 'system' | 'assistant' | 'user';
+    bubbleSenderName?: string;
 }
 export interface ProviderEffect {
     type: 'message' | 'toast' | 'notification';

package/dist/providers/control-effects.d.ts

@@ -1,7 +1,9 @@
 import type { ControlInvokeResult, ControlListResult, ControlSetResult, ProviderControlDef, ProviderEffect } from './contracts.js';
+import type { ChatMessage } from '../types.js';
 export type ProviderControlValue = string | number | boolean;
 export declare function extractProviderControlValues(controls: ProviderControlDef[] | undefined, data: any): Record<string, ProviderControlValue> | undefined;
 export declare function normalizeProviderEffects(data: any): ProviderEffect[];
+export declare function buildPersistedProviderEffectMessage(effect: ProviderEffect | null | undefined): ChatMessage | null;
 export declare function normalizeControlListResult(data: any): ControlListResult;
 export declare function normalizeControlSetResult(data: any): ControlSetResult;
 export declare function normalizeControlInvokeResult(data: any): ControlInvokeResult;

package/dist/providers/extension-provider-instance.d.ts

@@ -4,7 +4,7 @@
  * Manages IDE extensions (Cline, Roo Code, etc).
  * CDP webview discovery + agent stream collection moved here.
  */
-import type { ProviderModule } from './contracts.js';
+import { type ProviderModule } from './contracts.js';
 import type { ProviderInstance, ProviderState, InstanceContext } from './provider-instance.js';
 export declare class ExtensionProviderInstance implements ProviderInstance {
     readonly type: string;
@@ -45,6 +45,7 @@ export declare class ExtensionProviderInstance implements ProviderInstance {
     private pushEvent;
     private applyProviderResponse;
     private appendRuntimeSystemMessage;
+    private appendRuntimeMessage;
     /**
      * Assign stable receivedAt to extension messages.
      * Same pattern as IdeProviderInstance.readChat() prevByHash —

package/dist/providers/ide-provider-instance.d.ts

@@ -8,7 +8,7 @@
  * IDE Instance manages child Extension Instances.
  * Daemon collects all via a single IDE Instance.getState() call.
  */
-import type { ProviderModule } from './contracts.js';
+import { type ProviderModule } from './contracts.js';
 import type { ProviderInstance, ProviderState, InstanceContext } from './provider-instance.js';
 import { ExtensionProviderInstance } from './extension-provider-instance.js';
 export declare class IdeProviderInstance implements ProviderInstance {
@@ -60,6 +60,7 @@ export declare class IdeProviderInstance implements ProviderInstance {
     private pushEvent;
     private applyProviderResponse;
     private appendRuntimeSystemMessage;
+    private appendRuntimeMessage;
     private mergeConversationMessages;
     private getPersistedEffectContent;
     private getEffectDedupKey;

package/dist/types.d.ts

@@ -5,6 +5,7 @@
  * When modifying this file, also update interface contracts in AGENT_PROTOCOL.md.
  */
 import type { StatusReportPayload, AvailableProviderInfo } from './shared-types.js';
+import type { ChatMessageKind } from './providers/chat-message-normalization.js';
 /** Full status response from /api/v1/status and WS events */
 export interface StatusResponse extends StatusReportPayload {
     /** For standalone API compat */
@@ -23,7 +24,7 @@ export interface ChatMessage {
     role: string;
     /** Plain text (legacy) or canonical message parts */
     content: string | MessagePart[];
-    kind?: string;
+    kind?: ChatMessageKind;
     id?: string;
     index?: number;
     timestamp?: number;

package/node_modules/@adhdev/session-host-core/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adhdev/session-host-core",
-  "version": "0.8.60",
-  "description": "ADHDev local session host core — session registry, protocol, buffers",
+  "version": "0.8.62",
+  "description": "ADHDev local session host core \u2014 session registry, protocol, buffers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.8.60",
-  "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
+  "version": "0.8.62",
+  "description": "ADHDev daemon core \u2014 CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

package/src/agent-stream/poller.ts

@@ -21,6 +21,7 @@ import { LOG } from '../logging/logger.js';
 import type { AgentStreamState } from './types.js';
 import { formatAutoApprovalMessage, pickApprovalButton } from '../providers/approval-utils.js';
 import type { ProviderModule } from '../providers/contracts.js';
+import { buildRuntimeSystemChatMessage } from '../providers/chat-message-normalization.js';
 
 interface ExtensionInstanceLike {
     type?: string;
@@ -229,12 +230,9 @@ export class AgentStreamPoller {
                                         type: 'message',
                                         id: effectId,
                                         persist: true,
-                                        message: {
-                                            role: 'system',
-                                            senderName: 'System',
-                                            kind: 'system',
+                                        message: buildRuntimeSystemChatMessage({
                                             content: formatAutoApprovalMessage(stream.activeModal?.message, buttonLabel),
-                                        },
+                                        }),
                                     },
                                 ],
                             };

package/src/cli-adapters/provider-cli-adapter.ts

@@ -44,6 +44,7 @@ import {
     type CliSessionStatus,
     type CliTraceEntry,
 } from './provider-cli-shared.js';
+import { buildChatMessage } from '../providers/chat-message-normalization.js';
 import {
     buildCliParseInput,
     buildCliTraceParseSnapshot,
@@ -738,6 +739,19 @@ export class ProviderCliAdapter implements CliAdapter {
             || screenStableMs < holdMs;
     }
 
+    private shouldDeferIdleTimeoutFinish(): boolean {
+        if (!this.isWaitingForResponse || this.currentStatus === 'waiting_approval') {
+            return false;
+        }
+        const latestStatus = this.runDetectStatus(this.recentOutputBuffer) || this.currentStatus;
+        if (latestStatus === 'generating') {
+            this.settledBuffer = this.recentOutputBuffer;
+            this.evaluateSettled();
+            return true;
+        }
+        return false;
+    }
+
     private getStartupConfirmationModal(screenText: string): { message: string; buttons: string[] } | null {
         const text = sanitizeTerminalText(String(screenText || ''));
         if (!text.trim()) return null;
@@ -929,6 +943,7 @@ export class ProviderCliAdapter implements CliAdapter {
             if (this.idleTimeout) clearTimeout(this.idleTimeout);
             this.idleTimeout = setTimeout(() => {
                 if (this.isWaitingForResponse && this.currentStatus !== 'waiting_approval') {
+                    if (this.shouldDeferIdleTimeoutFinish()) return;
                     this.finishResponse();
                 }
             }, this.timeouts.generatingIdle);
@@ -962,6 +977,7 @@ export class ProviderCliAdapter implements CliAdapter {
                     if (this.idleTimeout) clearTimeout(this.idleTimeout);
                     this.idleTimeout = setTimeout(() => {
                         if (this.isWaitingForResponse && this.currentStatus !== 'waiting_approval') {
+                            if (this.shouldDeferIdleTimeoutFinish()) return;
                             this.finishResponse();
                         }
                     }, this.timeouts.generatingIdle);
@@ -1011,7 +1027,10 @@ export class ProviderCliAdapter implements CliAdapter {
             // Reset idle timeout
             if (this.idleTimeout) clearTimeout(this.idleTimeout);
             this.idleTimeout = setTimeout(() => {
-                if (this.isWaitingForResponse) this.finishResponse();
+                if (this.isWaitingForResponse) {
+                    if (this.shouldDeferIdleTimeoutFinish()) return;
+                    this.finishResponse();
+                }
             }, this.timeouts.generatingIdle);
             this.onStatusChange?.();
             return;
@@ -1090,6 +1109,7 @@ export class ProviderCliAdapter implements CliAdapter {
                 if (this.idleTimeout) clearTimeout(this.idleTimeout);
                 this.idleTimeout = setTimeout(() => {
                     if (this.isWaitingForResponse && this.currentStatus !== 'waiting_approval') {
+                        if (this.shouldDeferIdleTimeoutFinish()) return;
                         this.clearIdleFinishCandidate('idle_timeout_finish');
                         this.finishResponse();
                     }
@@ -1218,6 +1238,7 @@ export class ProviderCliAdapter implements CliAdapter {
                 tail: text.slice(-500),
                 screenText,
                 rawBuffer: this.accumulatedRawBuffer,
+                isWaitingForResponse: this.isWaitingForResponse,
                 screen: buildCliScreenSnapshot(screenText),
                 tailScreen: buildCliScreenSnapshot(text.slice(-500)),
             });
@@ -1297,11 +1318,10 @@ export class ProviderCliAdapter implements CliAdapter {
             && !this.activeModal;
         if (parsed && Array.isArray(parsed.messages)) {
             const hydratedMessages = shouldPreferCommittedMessages
-                ? this.committedMessages.map((message, index) => ({
+                ? this.committedMessages.map((message, index) => buildChatMessage({
                     ...message,
                     id: message.id || `msg_${index}`,
                     index: typeof message.index === 'number' ? message.index : index,
-                    kind: message.kind || 'standard',
                     receivedAt: typeof message.receivedAt === 'number'
                         ? message.receivedAt
                         : message.timestamp,
@@ -1326,13 +1346,13 @@ export class ProviderCliAdapter implements CliAdapter {
             id: 'cli_session',
             status: this.currentStatus,
             title: this.cliName,
-            messages: messages.slice(-50).map((message, index) => ({
-                id: `msg_${index}`,
-                role: message.role,
-                content: message.content,
-                timestamp: message.timestamp,
-                index,
-                kind: 'standard',
+            messages: messages.slice(-50).map((message, index) => buildChatMessage({
+                ...message,
+                id: message.id || `msg_${index}`,
+                index: typeof message.index === 'number' ? message.index : index,
+                receivedAt: typeof message.receivedAt === 'number'
+                    ? message.receivedAt
+                    : message.timestamp,
             })),
             activeModal: this.activeModal,
         };
@@ -1350,6 +1370,7 @@ export class ProviderCliAdapter implements CliAdapter {
             terminalScreenText: this.terminalScreen.getText(),
             baseMessages: this.committedMessages,
             partialResponse: this.responseBuffer,
+            isWaitingForResponse: this.isWaitingForResponse,
             scope: this.currentTurnScope,
             runtimeSettings: this.runtimeSettings,
         });
@@ -1369,6 +1390,7 @@ export class ProviderCliAdapter implements CliAdapter {
                 terminalScreenText: this.terminalScreen.getText(),
                 baseMessages,
                 partialResponse,
+                isWaitingForResponse: this.isWaitingForResponse,
                 scope,
                 runtimeSettings: this.runtimeSettings,
             });

package/src/cli-adapters/provider-cli-parse.d.ts

@@ -24,6 +24,7 @@ export declare function buildCliParseInput(options: {
     terminalScreenText: string;
     baseMessages: CliChatMessage[];
     partialResponse: string;
+    isWaitingForResponse?: boolean;
     scope?: TurnParseScope | null;
     runtimeSettings: Record<string, any>;
 }): CliScriptInput;

package/src/cli-adapters/provider-cli-parse.ts

@@ -123,6 +123,7 @@ export function buildCliParseInput(options: {
     terminalScreenText: string;
     baseMessages: CliChatMessage[];
     partialResponse: string;
+    isWaitingForResponse?: boolean;
     scope?: TurnParseScope | null;
     runtimeSettings: Record<string, any>;
 }): CliScriptInput {
@@ -133,6 +134,7 @@ export function buildCliParseInput(options: {
         terminalScreenText,
         baseMessages,
         partialResponse,
+        isWaitingForResponse,
         scope,
         runtimeSettings,
     } = options;
@@ -155,6 +157,7 @@ export function buildCliParseInput(options: {
         recentScreen: buildCliScreenSnapshot(recentBuffer),
         messages: [...baseMessages],
         partialResponse,
+        isWaitingForResponse,
         promptText: scope?.prompt || '',
         settings: { ...runtimeSettings },
     };

package/src/cli-adapters/provider-cli-shared.d.ts

@@ -62,6 +62,7 @@ export interface CliScriptInput {
     recentScreen: CliScreenSnapshot;
     messages: CliChatMessage[];
     partialResponse: string;
+    isWaitingForResponse?: boolean;
     promptText?: string;
     settings?: Record<string, any>;
     args?: Record<string, any>;
@@ -70,6 +71,7 @@ export interface CliStatusInput {
     tail: string;
     screenText?: string;
     rawBuffer?: string;
+    isWaitingForResponse?: boolean;
     screen: CliScreenSnapshot;
     tailScreen: CliScreenSnapshot;
 }

package/src/cli-adapters/provider-cli-shared.ts

@@ -2,6 +2,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import type { ProviderResumeCapability } from '../providers/contracts.js';
+import type { ChatMessageKind } from '../providers/chat-message-normalization.js';
 import { sanitizeSpawnEnv } from './spawn-env.js';
 
 export interface CliChatMessage {
@@ -9,10 +10,10 @@ export interface CliChatMessage {
     content: string;
     timestamp?: number;
     receivedAt?: number;
-    kind?: string;
+    kind?: ChatMessageKind;
     id?: string;
     index?: number;
-    meta?: Record<string, any>;
+    meta?: Record<string, unknown>;
     senderName?: string;
 }
 
@@ -65,6 +66,7 @@ export interface CliScriptInput {
     recentScreen: CliScreenSnapshot;
     messages: CliChatMessage[];
     partialResponse: string;
+    isWaitingForResponse?: boolean;
     promptText?: string;
     settings?: Record<string, any>;
     args?: Record<string, any>;
@@ -74,6 +76,7 @@ export interface CliStatusInput {
     tail: string;
     screenText?: string;
     rawBuffer?: string;
+    isWaitingForResponse?: boolean;
     screen: CliScreenSnapshot;
     tailScreen: CliScreenSnapshot;
 }

package/src/commands/chat-commands.ts

@@ -12,6 +12,7 @@ import { LOG } from '../logging/logger.js';
 import { recordDebugTrace } from '../logging/debug-trace.js';
 import type { ChatMessage } from '../types.js';
 import type { ReadChatCursor, ReadChatSyncMode, SessionTransport } from '../shared-types.js';
+import { normalizeChatMessages } from '../providers/chat-message-normalization.js';
 
 const RECENT_SEND_WINDOW_MS = 1200;
 const recentSendByTarget = new Map<string, number>();
@@ -189,7 +190,7 @@ function normalizeReadChatCursor(args: any): Required<ReadChatCursor> {
 
 function normalizeReadChatMessages(payload: Record<string, any>): ChatMessage[] {
     const messages = Array.isArray(payload.messages) ? payload.messages as ChatMessage[] : [];
-    return messages;
+    return normalizeChatMessages(messages);
 }
 
 function deriveHistoryDedupKey(message: ChatMessage & { _unitKey?: string; _turnKey?: string }): string | undefined {

package/src/config/chat-history.ts

@@ -12,6 +12,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { buildRuntimeSystemChatMessage } from '../providers/chat-message-normalization.js';
 
 const HISTORY_DIR = path.join(os.homedir(), '.adhdev', 'history');
 const RETAIN_DAYS = 30;
@@ -314,11 +315,11 @@ export class ChatHistoryWriter {
         this.appendNewMessages(
             agentType,
             [{
-                role: 'system',
-                kind: 'system',
-                content,
-                receivedAt: options.receivedAt,
-                senderName: options.senderName,
+                ...buildRuntimeSystemChatMessage({
+                    content,
+                    receivedAt: options.receivedAt,
+                    senderName: options.senderName,
+                }),
                 historyDedupKey: options.dedupKey,
             }],
             options.sessionTitle,

package/src/index.ts

@@ -200,6 +200,19 @@ export type { ProviderModule, CdpTargetFilter, ProviderResumeCapability, InputEn
 export type { ProviderSourceConfigSnapshot, ProviderSourceConfigUpdate } from './config/provider-source-config.js';
 export { parseProviderSourceConfigUpdate } from './config/provider-source-config.js';
 export { normalizeInputEnvelope, normalizeMessageParts, flattenMessageParts } from './providers/io-contracts.js';
+export {
+  BUILTIN_CHAT_MESSAGE_KINDS,
+  isBuiltinChatMessageKind,
+  normalizeChatMessageKind,
+  buildChatMessage,
+  buildSystemChatMessage,
+  buildRuntimeSystemChatMessage,
+  buildAssistantChatMessage,
+  buildUserChatMessage,
+  normalizeChatMessage,
+  normalizeChatMessages,
+} from './providers/chat-message-normalization.js';
+export type { BuiltinChatMessageKind, ChatMessageKind } from './providers/chat-message-normalization.js';
 export { VersionArchive, detectAllVersions } from './providers/version-archive.js';
 export type { ProviderVersionInfo, VersionHistory } from './providers/version-archive.js';
 

package/src/providers/acp-provider-instance.ts

@@ -51,15 +51,16 @@ import { normalizeContent, flattenContent, normalizeInputEnvelope } from './cont
 import type { ProviderInstance, ProviderState, AcpProviderState, ProviderErrorReason, ProviderEvent, InstanceContext } from './provider-instance.js';
 import { StatusMonitor } from './status-monitor.js';
 import { buildLegacyModelModeSummaryMetadata } from './summary-metadata.js';
+import { buildAssistantChatMessage, buildChatMessage, buildRuntimeSystemChatMessage, buildUserChatMessage, normalizeChatMessages } from './chat-message-normalization.js';
 import { LOG } from '../logging/logger.js';
+import type { ChatMessage } from '../types.js';
 
 // ─── Internal Display Types (for dashboard) ────────────────────────────
 
-interface AcpMessage {
+type AcpMessage = ChatMessage & {
     role: 'user' | 'assistant' | 'system';
     /** Rich content blocks (ACP standard) or plain text (legacy) */
     content: string | ContentBlock[];
-    timestamp?: number;
     /** Tool calls associated with this message */
     toolCalls?: ToolCallInfo[];
 }
@@ -293,26 +294,23 @@ export class AcpProviderInstance implements ProviderInstance {
         const dirName = this.workingDir.split('/').filter(Boolean).pop() || 'session';
 
  // Recent 50 messages
-        const recentMessages = this.messages.slice(-50).map(m => {
+        const recentMessages = normalizeChatMessages(this.messages.slice(-50).map(m => {
             const content = this.truncateContent(m.content);
-            return {
-                role: m.role,
+            return buildChatMessage({
+                ...m,
                 content,
-                timestamp: m.timestamp,
-                toolCalls: m.toolCalls,
-            };
-        });
+            });
+        }));
 
  // generating during partial response add
         if (this.currentStatus === 'generating' && (this.partialContent || this.partialBlocks.length > 0)) {
             const blocks = this.buildPartialBlocks();
             if (blocks.length > 0) {
-                recentMessages.push({
-                    role: 'assistant',
+                recentMessages.push(buildAssistantChatMessage({
                     content: blocks,
                     timestamp: Date.now(),
                     toolCalls: this.turnToolCalls.length > 0 ? [...this.turnToolCalls] : undefined,
-                });
+                }));
             }
         }
 
@@ -326,7 +324,7 @@ export class AcpProviderInstance implements ProviderInstance {
                 id: this.sessionId || `${this.type}_${this.workingDir}`,
                 title: `${this.provider.name} · ${dirName}`,
                 status: this.currentStatus,
-                messages: recentMessages,
+                messages: normalizeChatMessages(recentMessages as any),
                 activeModal: this.currentStatus === 'waiting_approval' ? {
                     message: this.activeToolCalls.find(t => t.status === 'running')?.name || 'Permission requested',
                     buttons: ['Approve', 'Reject'],
@@ -975,11 +973,10 @@ export class AcpProviderInstance implements ProviderInstance {
             : [{ type: 'text', text }];
 
  // Add user message locally (store as ContentBlock[])
-        this.messages.push({
-            role: 'user',
+        this.messages.push(buildUserChatMessage({
             content: contentBlocks && contentBlocks.length > 0 ? contentBlocks : text,
             timestamp: Date.now(),
-        });
+        }));
 
         this.currentStatus = 'generating';
         this.partialContent = '';
@@ -1181,11 +1178,11 @@ export class AcpProviderInstance implements ProviderInstance {
             }
 
             if (content.trim()) {
-                this.messages.push({
+                this.messages.push(buildChatMessage({
                     role: m.role || 'assistant',
                     content: content.trim(),
                     timestamp: Date.now(),
-                });
+                }));
                 this.partialContent = '';
             }
         }
@@ -1271,14 +1268,13 @@ export class AcpProviderInstance implements ProviderInstance {
         }).filter(b => b.type !== 'text' || (b.type === 'text' && b.text.trim()));
 
         if (finalBlocks.length > 0) {
-            this.messages.push({
-                role: 'assistant',
+            this.messages.push(buildAssistantChatMessage({
                 content: finalBlocks.length === 1 && finalBlocks[0].type === 'text'
                     ? (finalBlocks[0] as {type: 'text', text: string}).text   // single text → string (backward compat)
                     : finalBlocks,
                 timestamp: Date.now(),
                 toolCalls: this.turnToolCalls.length > 0 ? [...this.turnToolCalls] : undefined,
-            });
+            }));
         }
         this.partialContent = '';
         this.partialBlocks = [];
@@ -1347,11 +1343,10 @@ export class AcpProviderInstance implements ProviderInstance {
     private appendSystemMessage(content: string, timestamp = Date.now()): void {
         const normalizedContent = String(content || '').trim();
         if (!normalizedContent) return;
-        this.messages.push({
-            role: 'system',
+        this.messages.push(buildRuntimeSystemChatMessage({
             content: normalizedContent,
             timestamp,
-        });
+        }));
         if (this.messages.length > 200) {
             this.messages = this.messages.slice(-100);
         }

package/src/providers/chat-message-normalization.ts

@@ -0,0 +1,68 @@
+import type { ChatMessage } from '../types.js';
+
+export const BUILTIN_CHAT_MESSAGE_KINDS = ['standard', 'thought', 'tool', 'terminal', 'system'] as const;
+
+export type BuiltinChatMessageKind = typeof BUILTIN_CHAT_MESSAGE_KINDS[number];
+export type ChatMessageKind = BuiltinChatMessageKind | (string & {});
+
+const KNOWN_CHAT_MESSAGE_KINDS = new Set<string>(BUILTIN_CHAT_MESSAGE_KINDS);
+
+export function isBuiltinChatMessageKind(kind: unknown): kind is BuiltinChatMessageKind {
+  return typeof kind === 'string' && KNOWN_CHAT_MESSAGE_KINDS.has(kind.trim().toLowerCase());
+}
+
+export function normalizeChatMessageKind(kind: unknown, role: unknown): ChatMessageKind {
+  const normalizedKind = typeof kind === 'string' ? kind.trim().toLowerCase() : '';
+  if (normalizedKind && KNOWN_CHAT_MESSAGE_KINDS.has(normalizedKind)) return normalizedKind as BuiltinChatMessageKind;
+
+  const normalizedRole = typeof role === 'string' ? role.trim().toLowerCase() : '';
+  return normalizedRole === 'system' ? 'system' : 'standard';
+}
+
+export function buildChatMessage<T extends Omit<ChatMessage, 'kind'> & { kind?: ChatMessageKind }>(message: T): T & { kind: ChatMessageKind } {
+  return {
+    ...message,
+    kind: normalizeChatMessageKind(message?.kind, message?.role),
+  };
+}
+
+export function buildSystemChatMessage<T extends Omit<ChatMessage, 'role' | 'kind'> & { role?: 'system'; kind?: ChatMessageKind }>(message: T): (T & { role: 'system'; kind: ChatMessageKind }) {
+  return buildChatMessage({
+    ...message,
+    role: 'system',
+    kind: message?.kind || 'system',
+  } as T & { role: 'system'; kind?: ChatMessageKind }) as T & { role: 'system'; kind: ChatMessageKind };
+}
+
+export function buildRuntimeSystemChatMessage<T extends Omit<ChatMessage, 'role' | 'kind' | 'senderName'> & { role?: 'system'; kind?: ChatMessageKind; senderName?: string }>(message: T): (T & { role: 'system'; kind: ChatMessageKind; senderName: string }) {
+  return buildSystemChatMessage({
+    ...message,
+    senderName: typeof message?.senderName === 'string' && message.senderName.trim()
+      ? message.senderName
+      : 'System',
+  } as T & { role?: 'system'; kind?: ChatMessageKind; senderName?: string }) as T & { role: 'system'; kind: ChatMessageKind; senderName: string };
+}
+
+export function buildAssistantChatMessage<T extends Omit<ChatMessage, 'role' | 'kind'> & { role?: 'assistant'; kind?: ChatMessageKind }>(message: T): (T & { role: 'assistant'; kind: ChatMessageKind }) {
+  return buildChatMessage({
+    ...message,
+    role: 'assistant',
+    kind: message?.kind || 'standard',
+  } as T & { role: 'assistant'; kind?: ChatMessageKind }) as T & { role: 'assistant'; kind: ChatMessageKind };
+}
+
+export function buildUserChatMessage<T extends Omit<ChatMessage, 'role' | 'kind'> & { role?: 'user'; kind?: ChatMessageKind }>(message: T): (T & { role: 'user'; kind: ChatMessageKind }) {
+  return buildChatMessage({
+    ...message,
+    role: 'user',
+    kind: message?.kind || 'standard',
+  } as T & { role: 'user'; kind?: ChatMessageKind }) as T & { role: 'user'; kind: ChatMessageKind };
+}
+
+export function normalizeChatMessage<T extends ChatMessage>(message: T): T {
+  return buildChatMessage(message) as T;
+}
+
+export function normalizeChatMessages<T extends ChatMessage>(messages: T[] | null | undefined): T[] {
+  return (Array.isArray(messages) ? messages : []).map((message) => normalizeChatMessage(message));
+}