@adhdev/daemon-core 0.8.59 → 0.8.61

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.59",
-  "description": "ADHDev local session host core — session registry, protocol, buffers",
+  "version": "0.8.61",
+  "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.59",
-  "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
+  "version": "0.8.61",
+  "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,
@@ -183,6 +184,7 @@ export class ProviderCliAdapter implements CliAdapter {
     private static readonly MAX_TRACE_ENTRIES = 250;
     private readonly providerResolutionMeta: ProviderResolutionMeta;
     private static readonly IDLE_FINISH_CONFIRM_MS = 2000;
+    private static readonly HERMES_IDLE_FINISH_CONFIRM_MS = 5000;
     private static readonly STATUS_ACTIVITY_HOLD_MS = 2000;
     private static readonly FINISH_RETRY_DELAY_MS = 300;
     private static readonly MAX_FINISH_RETRIES = 2;
@@ -192,6 +194,18 @@ export class ProviderCliAdapter implements CliAdapter {
         this.structuredMessages = [...this.committedMessages];
     }
 
+    private getIdleFinishConfirmMs(): number {
+        return this.cliType === 'hermes-cli'
+            ? ProviderCliAdapter.HERMES_IDLE_FINISH_CONFIRM_MS
+            : ProviderCliAdapter.IDLE_FINISH_CONFIRM_MS;
+    }
+
+    private getStatusActivityHoldMs(): number {
+        return this.cliType === 'hermes-cli'
+            ? ProviderCliAdapter.HERMES_IDLE_FINISH_CONFIRM_MS
+            : ProviderCliAdapter.STATUS_ACTIVITY_HOLD_MS;
+    }
+
     private setStatus(status: CliSessionStatus['status'], trigger?: string): void {
         const prev = this.currentStatus;
         if (prev === status) return;
@@ -216,6 +230,7 @@ export class ProviderCliAdapter implements CliAdapter {
 
     private armIdleFinishCandidate(assistantLength: number): void {
         const now = Date.now();
+        const idleFinishConfirmMs = this.getIdleFinishConfirmMs();
         this.idleFinishCandidate = {
             armedAt: now,
             lastOutputAt: this.lastOutputAt,
@@ -224,7 +239,7 @@ export class ProviderCliAdapter implements CliAdapter {
             assistantLength,
         };
         this.recordTrace('idle_candidate_armed', {
-            confirmMs: ProviderCliAdapter.IDLE_FINISH_CONFIRM_MS,
+            confirmMs: idleFinishConfirmMs,
             candidate: this.idleFinishCandidate,
             ...buildCliTraceParseSnapshot({
                 accumulatedBuffer: this.accumulatedBuffer,
@@ -239,7 +254,7 @@ export class ProviderCliAdapter implements CliAdapter {
             this.settleTimer = null;
             this.settledBuffer = this.recentOutputBuffer;
             this.evaluateSettled();
-        }, ProviderCliAdapter.IDLE_FINISH_CONFIRM_MS);
+        }, idleFinishConfirmMs);
     }
 
 
@@ -719,8 +734,9 @@ export class ProviderCliAdapter implements CliAdapter {
     private hasRecentInteractiveActivity(now: number): boolean {
         const quietForMs = this.lastNonEmptyOutputAt ? (now - this.lastNonEmptyOutputAt) : Number.MAX_SAFE_INTEGER;
         const screenStableMs = this.lastScreenChangeAt ? (now - this.lastScreenChangeAt) : Number.MAX_SAFE_INTEGER;
-        return quietForMs < ProviderCliAdapter.STATUS_ACTIVITY_HOLD_MS
-            || screenStableMs < ProviderCliAdapter.STATUS_ACTIVITY_HOLD_MS;
+        const holdMs = this.getStatusActivityHoldMs();
+        return quietForMs < holdMs
+            || screenStableMs < holdMs;
     }
 
     private getStartupConfirmationModal(screenText: string): { message: string; buttons: string[] } | null {
@@ -901,6 +917,7 @@ export class ProviderCliAdapter implements CliAdapter {
         }
 
         const recentInteractiveActivity = this.hasRecentInteractiveActivity(now);
+        const statusActivityHoldMs = this.getStatusActivityHoldMs();
         const shouldHoldGenerating =
             scriptStatus === 'idle'
             && this.isWaitingForResponse
@@ -921,7 +938,7 @@ export class ProviderCliAdapter implements CliAdapter {
                 recentInteractiveActivity,
                 lastNonEmptyOutputAt: this.lastNonEmptyOutputAt,
                 lastScreenChangeAt: this.lastScreenChangeAt,
-                holdMs: ProviderCliAdapter.STATUS_ACTIVITY_HOLD_MS,
+                holdMs: statusActivityHoldMs,
                 ...buildCliTraceParseSnapshot({
                     accumulatedBuffer: this.accumulatedBuffer,
                     accumulatedRawBuffer: this.accumulatedRawBuffer,
@@ -1013,8 +1030,9 @@ export class ProviderCliAdapter implements CliAdapter {
                 const screenStableMs = this.lastScreenChangeAt ? (now - this.lastScreenChangeAt) : 0;
                 const hasAssistantTurn = !!lastParsedAssistant;
                 const assistantLength = lastParsedAssistant?.content?.length || 0;
-                const idleQuietThresholdMs = Math.max(2000, this.timeouts.outputSettle);
-                const idleStableThresholdMs = 2000;
+                const idleFinishConfirmMs = this.getIdleFinishConfirmMs();
+                const idleQuietThresholdMs = Math.max(idleFinishConfirmMs, this.timeouts.outputSettle);
+                const idleStableThresholdMs = idleFinishConfirmMs;
                 const idleReady = visibleIdlePrompt
                     && !modal
                     && hasAssistantTurn
@@ -1026,7 +1044,7 @@ export class ProviderCliAdapter implements CliAdapter {
                     && candidate.lastOutputAt === this.lastOutputAt
                     && candidate.lastScreenChangeAt === this.lastScreenChangeAt
                     && assistantLength >= candidate.assistantLength
-                    && (now - candidate.armedAt) >= ProviderCliAdapter.IDLE_FINISH_CONFIRM_MS;
+                    && (now - candidate.armedAt) >= idleFinishConfirmMs;
                 const canFinishImmediately = idleReady && candidateQuiet;
 
                 this.recordTrace('idle_decision', {
@@ -1039,7 +1057,7 @@ export class ProviderCliAdapter implements CliAdapter {
                     idleQuietThresholdMs,
                     idleStableThresholdMs,
                     idleReady,
-                    idleFinishConfirmMs: ProviderCliAdapter.IDLE_FINISH_CONFIRM_MS,
+                    idleFinishConfirmMs,
                     idleFinishCandidate: candidate,
                     candidateQuiet,
                     canFinishImmediately,
@@ -1280,11 +1298,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,
@@ -1309,13 +1326,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,
         };

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;
 }
 

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));
+}