@adhdev/daemon-core 0.9.76-rc.8 → 0.9.76

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

@@ -5,6 +5,43 @@ export const BUILTIN_CHAT_MESSAGE_KINDS = ['standard', 'thought', 'tool', 'termi
 export type BuiltinChatMessageKind = typeof BUILTIN_CHAT_MESSAGE_KINDS[number];
 export type ChatMessageKind = BuiltinChatMessageKind | (string & {});
 
+export const CHAT_MESSAGE_VISIBILITIES = ['user', 'debug', 'internal', 'hidden'] as const;
+export const CHAT_MESSAGE_TRANSCRIPT_VISIBILITIES = ['visible', 'chat', 'user', 'debug', 'internal', 'hidden'] as const;
+export const CHAT_MESSAGE_AUDIENCES = ['chat', 'debug', 'trace', 'internal'] as const;
+export const CHAT_MESSAGE_SOURCES = [
+  'assistant_text',
+  'tool_call',
+  'terminal_command',
+  'runtime_activity',
+  'runtime_status',
+  'provider_chrome',
+  'control',
+] as const;
+export const CHAT_MESSAGE_ACTIVITY_SOURCES = ['tool_call', 'terminal_command', 'runtime_activity'] as const;
+export const CHAT_MESSAGE_INTERNAL_SOURCES = ['runtime_status', 'provider_chrome', 'control'] as const;
+
+export type ChatMessageVisibility = typeof CHAT_MESSAGE_VISIBILITIES[number] | (string & {});
+export type ChatMessageTranscriptVisibility = typeof CHAT_MESSAGE_TRANSCRIPT_VISIBILITIES[number] | (string & {});
+export type ChatMessageAudience = typeof CHAT_MESSAGE_AUDIENCES[number] | (string & {});
+export type ChatMessageSource = typeof CHAT_MESSAGE_SOURCES[number] | (string & {});
+export type ChatMessageTranscriptSurface = 'chat' | 'activity' | 'internal';
+
+export interface ChatMessageVisibilityClassification {
+  surface: ChatMessageTranscriptSurface;
+  isUserFacing: boolean;
+  isActivityFacing: boolean;
+  isInternal: boolean;
+  explicitUserFacing: boolean;
+  explicitHidden: boolean;
+  role: string;
+  kind: ChatMessageKind;
+  visibility: string;
+  transcriptVisibility: string;
+  audience: string;
+  source: string;
+}
+
+
 const KNOWN_CHAT_MESSAGE_KINDS = new Set<string>(BUILTIN_CHAT_MESSAGE_KINDS);
 const CHAT_MESSAGE_KIND_ALIASES: Record<string, BuiltinChatMessageKind> = {
   text: 'standard',
@@ -171,3 +208,207 @@ export function normalizeChatMessage<T extends ChatMessage>(message: T): T {
 export function normalizeChatMessages<T extends ChatMessage>(messages: T[] | null | undefined): T[] {
   return (Array.isArray(messages) ? messages : []).map((message) => normalizeChatMessage(message));
 }
+
+function readMessageMeta(message: ChatMessage): Record<string, unknown> | null {
+  const meta = message?.meta;
+  return meta && typeof meta === 'object' && !Array.isArray(meta)
+    ? meta as Record<string, unknown>
+    : null;
+}
+
+function readStringField(value: unknown): string {
+  return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+
+function readRecordField(message: ChatMessage, meta: Record<string, unknown> | null, key: string): unknown {
+  const record = message as ChatMessage & Record<string, unknown>;
+  return record[key] ?? meta?.[key];
+}
+
+function readVisibilityField(message: ChatMessage, meta: Record<string, unknown> | null): string {
+  return readStringField(readRecordField(message, meta, 'visibility'));
+}
+
+function readTranscriptVisibilityField(message: ChatMessage, meta: Record<string, unknown> | null): string {
+  const record = message as ChatMessage & Record<string, unknown>;
+  return readStringField(record.transcriptVisibility ?? meta?.transcriptVisibility ?? record.visibility ?? meta?.visibility);
+}
+
+const EXPLICIT_HIDDEN_VISIBILITIES = new Set(['hidden', 'debug', 'internal']);
+const EXPLICIT_VISIBLE_VISIBILITIES = new Set(['visible', 'user', 'chat']);
+const HIDDEN_AUDIENCES = new Set(['debug', 'trace', 'internal']);
+const ACTIVITY_SOURCE_SET = new Set<string>(CHAT_MESSAGE_ACTIVITY_SOURCES);
+const INTERNAL_SOURCE_SET = new Set<string>(CHAT_MESSAGE_INTERNAL_SOURCES);
+
+function hasBooleanMarker(message: ChatMessage, meta: Record<string, unknown> | null, keys: string[]): boolean {
+  const record = message as ChatMessage & Record<string, unknown>;
+  return keys.some((key) => record[key] === true || meta?.[key] === true);
+}
+
+function isActivityKind(kind: ChatMessageKind): boolean {
+  return kind === 'thought' || kind === 'tool' || kind === 'terminal';
+}
+
+function isOrdinaryVisibleTurn(message: ChatMessage, role: string, kind: ChatMessageKind): boolean {
+  if (role === 'user' || role === 'human') return kind === 'standard' || kind === '';
+  if (role === 'assistant') return kind === 'standard' || kind === '';
+  return false;
+}
+
+/**
+ * Shared transcript visibility protocol for all ADHDev provider chat messages.
+ *
+ * Producers can stamp visibility/audience/source/userFacing/internal/debug either
+ * at the top level or under `meta`. Consumers should use this classifier instead
+ * of matching command text, icons, provider names, or terminal UI fragments.
+ */
+export function classifyChatMessageVisibility(message: ChatMessage | null | undefined): ChatMessageVisibilityClassification {
+  if (!message) {
+    return {
+      surface: 'internal',
+      isUserFacing: false,
+      isActivityFacing: false,
+      isInternal: true,
+      explicitUserFacing: false,
+      explicitHidden: true,
+      role: '',
+      kind: 'standard',
+      visibility: '',
+      transcriptVisibility: '',
+      audience: '',
+      source: '',
+    };
+  }
+
+  const meta = readMessageMeta(message);
+  const role = typeof message.role === 'string' ? message.role.trim().toLowerCase() : '';
+  const kind = resolveChatMessageKind(message);
+  const visibility = readVisibilityField(message, meta);
+  const transcriptVisibility = readTranscriptVisibilityField(message, meta);
+  const audience = readStringField(readRecordField(message, meta, 'audience'));
+  const source = readStringField(readRecordField(message, meta, 'source'));
+  const explicitHidden = EXPLICIT_HIDDEN_VISIBILITIES.has(visibility)
+    || EXPLICIT_HIDDEN_VISIBILITIES.has(transcriptVisibility)
+    || HIDDEN_AUDIENCES.has(audience)
+    || hasBooleanMarker(message, meta, ['internal', 'isInternal', 'debug', 'statusOnly', 'controlOnly']);
+  const explicitUserFacing = EXPLICIT_VISIBLE_VISIBILITIES.has(visibility)
+    || EXPLICIT_VISIBLE_VISIBILITIES.has(transcriptVisibility)
+    || audience === 'chat'
+    || hasBooleanMarker(message, meta, ['userFacing']);
+
+  if (explicitHidden) {
+    const activityLike = isActivityKind(kind) || ACTIVITY_SOURCE_SET.has(source);
+    return {
+      surface: activityLike ? 'activity' : 'internal',
+      isUserFacing: false,
+      isActivityFacing: activityLike,
+      isInternal: !activityLike,
+      explicitUserFacing,
+      explicitHidden,
+      role,
+      kind,
+      visibility,
+      transcriptVisibility,
+      audience,
+      source,
+    };
+  }
+
+  if (explicitUserFacing) {
+    return {
+      surface: 'chat',
+      isUserFacing: true,
+      isActivityFacing: false,
+      isInternal: false,
+      explicitUserFacing,
+      explicitHidden,
+      role,
+      kind,
+      visibility,
+      transcriptVisibility,
+      audience,
+      source,
+    };
+  }
+
+  if (INTERNAL_SOURCE_SET.has(source) || role === 'system' || kind === 'system') {
+    return {
+      surface: 'internal',
+      isUserFacing: false,
+      isActivityFacing: false,
+      isInternal: true,
+      explicitUserFacing,
+      explicitHidden,
+      role,
+      kind,
+      visibility,
+      transcriptVisibility,
+      audience,
+      source,
+    };
+  }
+
+  if (ACTIVITY_SOURCE_SET.has(source) || isActivityKind(kind)) {
+    return {
+      surface: 'activity',
+      isUserFacing: false,
+      isActivityFacing: true,
+      isInternal: false,
+      explicitUserFacing,
+      explicitHidden,
+      role,
+      kind,
+      visibility,
+      transcriptVisibility,
+      audience,
+      source,
+    };
+  }
+
+  const isUserFacing = isOrdinaryVisibleTurn(message, role, kind);
+  return {
+    surface: isUserFacing ? 'chat' : 'internal',
+    isUserFacing,
+    isActivityFacing: false,
+    isInternal: !isUserFacing,
+    explicitUserFacing,
+    explicitHidden,
+    role,
+    kind,
+    visibility,
+    transcriptVisibility,
+    audience,
+    source,
+  };
+}
+
+export function isUserFacingChatMessage(message: ChatMessage | null | undefined): boolean {
+  return classifyChatMessageVisibility(message).isUserFacing;
+}
+
+export function isActivityChatMessage(message: ChatMessage | null | undefined): boolean {
+  return classifyChatMessageVisibility(message).isActivityFacing;
+}
+
+export function isInternalChatMessage(message: ChatMessage | null | undefined): boolean {
+  return classifyChatMessageVisibility(message).isInternal;
+}
+
+export function filterUserFacingChatMessages<T extends ChatMessage>(messages: T[] | null | undefined): T[] {
+  return (Array.isArray(messages) ? messages : []).filter((message) => isUserFacingChatMessage(message));
+}
+
+export function filterActivityChatMessages<T extends ChatMessage>(messages: T[] | null | undefined): T[] {
+  return (Array.isArray(messages) ? messages : []).filter((message) => isActivityChatMessage(message));
+}
+
+export function filterInternalChatMessages<T extends ChatMessage>(messages: T[] | null | undefined): T[] {
+  return (Array.isArray(messages) ? messages : []).filter((message) => isInternalChatMessage(message));
+}
+
+export function filterChatMessagesByVisibility<T extends ChatMessage>(
+  messages: T[] | null | undefined,
+  surface: ChatMessageTranscriptSurface,
+): T[] {
+  return (Array.isArray(messages) ? messages : []).filter((message) => classifyChatMessageVisibility(message).surface === surface);
+}

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

@@ -6,6 +6,7 @@
  */
 import type { ProviderModule } from './contracts.js';
 import type { ProviderInstance, ProviderState, InstanceContext } from './provider-instance.js';
+import type { ChatMessage } from '../types.js';
 import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
 import type { PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 export declare class CliProviderInstance implements ProviderInstance {
@@ -77,6 +78,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private formatMarkerTimestamp;
     private maybeAppendRuntimeRecoveryMessage;
     private appendRuntimeSystemMessage;
+    mergeRuntimeChatMessages(parsedMessages: ChatMessage[]): ChatMessage[];
     private mergeConversationMessages;
     private formatApprovalRequestMessage;
     private promoteProviderSessionId;

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

@@ -10,8 +10,8 @@ import * as path from 'path';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import { createRequire } from 'node:module';
-import { normalizeInputEnvelope, type ProviderModule, flattenContent } from './contracts.js';
-import { assertTextOnlyInput } from './provider-input-support.js';
+import { normalizeInputEnvelope, type ProviderModule, flattenContent, type InputEnvelope, type InputPart } from './contracts.js';
+import { assertProviderSupportsDeclaredInput, getEffectiveMessageInputSupport } from './provider-input-support.js';
 import type { ProviderInstance, ProviderState, ProviderEvent, InstanceContext, ProviderErrorReason, HotChatSessionState, SessionModalState } from './provider-instance.js';
 import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
 import type { CliProviderModule } from '../cli-adapters/provider-cli-adapter.js';
@@ -25,7 +25,7 @@ import { formatAutoApprovalMessage, pickApprovalButton } from './approval-utils.
 import { getCliScriptCommand, parseCliScriptResult } from './cli-script-results.js';
 import { mergeProviderPatchState, resolveProviderStateSurface } from './provider-patch-state.js';
 import { normalizeProviderSessionId } from './provider-session-id.js';
-import { buildChatMessage, buildRuntimeSystemChatMessage, normalizeChatMessages } from './chat-message-normalization.js';
+import { buildChatMessage, buildRuntimeSystemChatMessage, isUserFacingChatMessage, normalizeChatMessages, resolveChatMessageKind } from './chat-message-normalization.js';
 
 type PersistableCliHistoryMessage = {
     role: string;
@@ -35,6 +35,125 @@ type PersistableCliHistoryMessage = {
     receivedAt?: number;
 };
 
+const IMAGE_MIME_EXTENSIONS: Record<string, string> = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/jpg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/bmp': '.bmp',
+    'image/tiff': '.tiff',
+    'image/svg+xml': '.svg',
+};
+
+function filePathFromUri(uri: string): string | null {
+    if (!uri) return null;
+    if (uri.startsWith('file://')) {
+        try {
+            return decodeURIComponent(new URL(uri).pathname);
+        } catch {
+            return uri.slice('file://'.length);
+        }
+    }
+    if (path.isAbsolute(uri)) return uri;
+    return null;
+}
+
+function extensionForImageMime(mimeType: string): string {
+    return IMAGE_MIME_EXTENSIONS[mimeType.toLowerCase()] || '.img';
+}
+
+function safeInputImageBasename(index: number, mimeType: string): string {
+    const extension = extensionForImageMime(mimeType);
+    const suffix = crypto.randomBytes(6).toString('hex');
+    return `adhdev-input-image-${Date.now()}-${index}-${suffix}${extension}`;
+}
+
+function materializeImageDataPart(part: Extract<InputPart, { type: 'image' }>, index: number, dir: string): string | null {
+    if (!part.data) return null;
+    const rawData = part.data.includes(',') ? part.data.split(',').pop() || '' : part.data;
+    if (!rawData) return null;
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, safeInputImageBasename(index, part.mimeType));
+    fs.writeFileSync(filePath, Buffer.from(rawData, 'base64'));
+    cleanupStaleMaterializedImages(dir);
+    return filePath;
+}
+
+const MATERIALIZED_IMAGE_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
+const MATERIALIZED_IMAGE_CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+let lastMaterializedImageCleanupAt = 0;
+
+function cleanupStaleMaterializedImages(dir: string): void {
+    const now = Date.now();
+    if (now - lastMaterializedImageCleanupAt < MATERIALIZED_IMAGE_CLEANUP_INTERVAL_MS) return;
+    lastMaterializedImageCleanupAt = now;
+    try {
+        const entries = fs.readdirSync(dir);
+        for (const entry of entries) {
+            if (!entry.startsWith('adhdev-input-image-')) continue;
+            const fullPath = path.join(dir, entry);
+            try {
+                const stat = fs.statSync(fullPath);
+                if (now - stat.mtimeMs > MATERIALIZED_IMAGE_MAX_AGE_MS) {
+                    fs.unlinkSync(fullPath);
+                }
+            } catch { /* file may have been removed concurrently */ }
+        }
+    } catch { /* dir may not exist or be inaccessible */ }
+}
+
+export function buildCliStructuredInputPrompt(
+    input: InputEnvelope,
+    options: { materializeDir?: string } = {},
+): string {
+    const promptParts: string[] = [];
+    const imageRefs: string[] = [];
+    const resourceRefs: string[] = [];
+    const materializeDir = options.materializeDir || path.join(os.tmpdir(), 'adhdev-input-media');
+
+    input.parts.forEach((part, index) => {
+        if (part.type === 'text' && part.text.trim()) {
+            promptParts.push(part.text.trim());
+            return;
+        }
+
+        if (part.type === 'image') {
+            const localPath = typeof part.uri === 'string' ? filePathFromUri(part.uri) : null;
+            const materializedPath = !localPath && part.data ? materializeImageDataPart(part, index, materializeDir) : null;
+            const ref = localPath || materializedPath || part.uri || '';
+            if (ref) imageRefs.push(ref);
+            if (part.alt?.trim()) promptParts.push(part.alt.trim());
+            return;
+        }
+
+        if (part.type === 'resource_link') {
+            resourceRefs.push([part.title, part.name, part.description, part.uri].filter(Boolean).join('\n'));
+            return;
+        }
+
+        if (part.type === 'resource') {
+            resourceRefs.push([part.name, part.text, part.uri].filter(Boolean).join('\n'));
+        }
+    });
+
+    // Only use textFallback when no explicit text parts were collected — it is
+    // the flattened version of the same parts, so appending it alongside them
+    // would duplicate the content for multipart inputs.
+    const hasExplicitTextParts = input.parts.some((part) => part.type === 'text' && part.text.trim());
+    if (!hasExplicitTextParts && input.textFallback.trim()) {
+        promptParts.push(input.textFallback.trim());
+    }
+
+    const ordered = [
+        ...imageRefs,
+        ...promptParts,
+        ...resourceRefs,
+    ].filter((value, index, values) => value.trim().length > 0 && values.indexOf(value) === index);
+
+    return ordered.join('\n');
+}
+
 function normalizePersistableCliHistoryContent(content: unknown): string {
     return flattenContent(content as any).replace(/\s+/g, ' ').trim();
 }
@@ -214,6 +333,7 @@ export class CliProviderInstance implements ProviderInstance {
         options?: {
             providerSessionId?: string;
             launchMode?: 'new' | 'resume' | 'manual';
+            extraEnv?: Record<string, string>;
             onProviderSessionResolved?: (info: {
                 instanceId: string;
                 providerType: string;
@@ -230,7 +350,7 @@ export class CliProviderInstance implements ProviderInstance {
         this.providerSessionId = options?.providerSessionId;
         this.launchMode = options?.launchMode || 'new';
         this.onProviderSessionResolved = options?.onProviderSessionResolved;
-        this.adapter = new ProviderCliAdapter(provider as CliProviderModule, workingDir, cliArgs, transportFactory);
+        this.adapter = new ProviderCliAdapter(provider as CliProviderModule, workingDir, cliArgs, options?.extraEnv || {}, transportFactory);
         this.monitor = new StatusMonitor();
         this.historyWriter = new ChatHistoryWriter();
     }
@@ -475,6 +595,7 @@ export class CliProviderInstance implements ProviderInstance {
             resume: this.provider.resume,
             controlValues: surface.controlValues,
             providerControls: this.provider.controls,
+            messageInput: getEffectiveMessageInputSupport(this.provider),
             summaryMetadata: surface.summaryMetadata as any,
             errorMessage: this.errorMessage,
             errorReason: this.errorReason,
@@ -531,9 +652,10 @@ export class CliProviderInstance implements ProviderInstance {
     onEvent(event: string, data?: any): void {
         if (event === 'send_message') {
             const input = normalizeInputEnvelope(data);
-            assertTextOnlyInput(this.provider, input);
-            if (input.textFallback) {
-                void this.adapter.sendMessage(input.textFallback).catch((e: any) => {
+            assertProviderSupportsDeclaredInput(this.provider, input);
+            const promptText = buildCliStructuredInputPrompt(input);
+            if (promptText) {
+                void this.adapter.sendMessage(promptText).catch((e: any) => {
                     LOG.warn('CLI', `[${this.type}] send_message failed: ${e?.message || e}`);
                 });
             }
@@ -737,7 +859,29 @@ export class CliProviderInstance implements ProviderInstance {
     }
 
     private pushEvent(event: ProviderEvent): void {
-        this.events.push(event);
+        const enrichedEvent: ProviderEvent = {
+            ...event,
+            instanceId: typeof event.instanceId === 'string' && event.instanceId.trim()
+                ? event.instanceId
+                : this.instanceId,
+            targetSessionId: typeof event.targetSessionId === 'string' && event.targetSessionId.trim()
+                ? event.targetSessionId
+                : this.instanceId,
+            providerType: typeof event.providerType === 'string' && event.providerType.trim()
+                ? event.providerType
+                : this.type,
+            workspaceName: typeof event.workspaceName === 'string' && event.workspaceName.trim()
+                ? event.workspaceName
+                : this.workingDir,
+            providerSessionId: typeof event.providerSessionId === 'string' && event.providerSessionId.trim()
+                ? event.providerSessionId
+                : this.providerSessionId,
+        };
+        if (this.context?.emitProviderEvent) {
+            this.context.emitProviderEvent(enrichedEvent);
+            return;
+        }
+        this.events.push(enrichedEvent);
     }
 
     private flushEvents(): ProviderEvent[] {
@@ -977,15 +1121,77 @@ export class CliProviderInstance implements ProviderInstance {
         }
     }
 
+    mergeRuntimeChatMessages(parsedMessages: ChatMessage[]): ChatMessage[] {
+        return this.mergeConversationMessages(parsedMessages);
+    }
+
     private mergeConversationMessages(parsedMessages: any[]): ChatMessage[] {
         if (this.runtimeMessages.length === 0) return normalizeChatMessages(parsedMessages);
 
-        return normalizeChatMessages([...parsedMessages, ...this.runtimeMessages.map((entry) => entry.message)]
-            .map((message, index) => ({ message, index }))
+        type MergeEntry = { message: ChatMessage; index: number; source: 'parsed' | 'runtime'; runtimeKey?: string };
+        const parsedEntries: MergeEntry[] = parsedMessages.map((message, index) => ({
+            message,
+            index,
+            source: 'parsed',
+        }));
+        const runtimeEntries: MergeEntry[] = this.runtimeMessages.map((entry, index) => ({
+            message: entry.message,
+            index: parsedMessages.length + index,
+            source: 'runtime',
+            runtimeKey: entry.key,
+        }));
+        const getTime = (message: ChatMessage): number => {
+            const value = typeof message.receivedAt === 'number'
+                ? message.receivedAt
+                : typeof message.timestamp === 'number'
+                    ? message.timestamp
+                    : 0;
+            return Number.isFinite(value) && value > 0 ? value : 0;
+        };
+
+        const getRole = (message: ChatMessage): string => typeof message.role === 'string'
+            ? message.role.trim().toLowerCase()
+            : '';
+        const isRuntimeOverlay = (entry: MergeEntry): boolean => {
+            if (entry.source !== 'runtime') return false;
+            const key = typeof entry.runtimeKey === 'string' ? entry.runtimeKey.trim().toLowerCase() : '';
+            if (key.startsWith('auto_approval:')) return true;
+            return !isUserFacingChatMessage(entry.message);
+        };
+        const shouldKeepParsedBeforeUntimedRuntime = (message: ChatMessage): boolean => {
+            const role = getRole(message);
+            return role === 'user' || role === 'human';
+        };
+        const shouldKeepParsedAfterUntimedRuntime = (message: ChatMessage): boolean => {
+            const role = getRole(message);
+            if (role !== 'assistant') return false;
+            const kind = resolveChatMessageKind(message);
+            return kind === 'standard' || kind === 'terminal';
+        };
+
+        return normalizeChatMessages([...parsedEntries, ...runtimeEntries]
             .sort((a, b) => {
-                const aTime = a.message.receivedAt || a.message.timestamp || 0;
-                const bTime = b.message.receivedAt || b.message.timestamp || 0;
-                if (aTime !== bTime) return aTime - bTime;
+                const aTime = getTime(a.message);
+                const bTime = getTime(b.message);
+                if (aTime && bTime && aTime !== bTime) return aTime - bTime;
+                if (a.source !== b.source && aTime !== bTime) {
+                    const parsedEntry = a.source === 'parsed' ? a : b.source === 'parsed' ? b : null;
+                    const runtimeEntry = a.source === 'runtime' ? a : b.source === 'runtime' ? b : null;
+                    if (parsedEntry && runtimeEntry && isRuntimeOverlay(runtimeEntry) && getTime(parsedEntry.message) === 0 && getTime(runtimeEntry.message) > 0) {
+                        if (shouldKeepParsedBeforeUntimedRuntime(parsedEntry.message)) {
+                            return a.source === 'parsed' ? -1 : 1;
+                        }
+                        if (shouldKeepParsedAfterUntimedRuntime(parsedEntry.message)) {
+                            return a.source === 'parsed' ? 1 : -1;
+                        }
+                    }
+                }
+                // Many provider-owned CLI transcripts (including Hermes CLI in debug bundles)
+                // do not carry timestamps on parsed messages. In that case there is no safe
+                // clock basis for interleaving timestamped runtime/system messages into the
+                // provider transcript. Keep user prompts before runtime overlays, but do not
+                // let timed runtime/system/tool/internal overlays become the final chat turns
+                // after an untimed parsed assistant transcript.
                 return a.index - b.index;
             })
             .map((entry) => entry.message));

package/src/providers/contracts.ts

@@ -128,6 +128,7 @@ export type ContentBlock =
   | TextBlock
   | ImageBlock
   | AudioBlock
+  | VideoBlock
   | ResourceLinkBlock
   | ResourceBlock;
 
@@ -144,6 +145,7 @@ export interface ImageBlock {
   data: string;       // base64-encoded
   mimeType: string;   // 'image/png', 'image/jpeg', etc.
   uri?: string;       // optional URL reference
+  alt?: string;
   annotations?: ContentAnnotations;
 }
 
@@ -152,6 +154,19 @@ export interface AudioBlock {
   type: 'audio';
   data: string;       // base64-encoded
   mimeType: string;
+  uri?: string;
+  transcript?: string;
+  annotations?: ContentAnnotations;
+}
+
+/** Video content — ADHDev canonical display block. ACP prompt input degrades video to resource_link/text. */
+export interface VideoBlock {
+  type: 'video';
+  data?: string;      // base64-encoded
+  mimeType: string;
+  uri?: string;
+  transcript?: string;
+  posterUri?: string;
   annotations?: ContentAnnotations;
 }
 
@@ -595,7 +610,16 @@ export interface ProviderModule {
  // ─── Contract version / capability declaration ───
   contractVersion?: number;
   capabilities?: {
-    input?: { multipart?: boolean; mediaTypes?: Array<'text' | 'image' | 'audio' | 'video' | 'resource'> };
+    input?: {
+      multipart?: boolean;
+      mediaTypes?: Array<'text' | 'image' | 'audio' | 'video' | 'resource'>;
+      strategies?: Array<{
+        mediaType: 'text' | 'image' | 'audio' | 'video' | 'resource';
+        strategies?: Array<'native' | 'native_acp' | 'resource_link' | 'text_fallback' | 'paste' | 'upload'>;
+        native?: boolean;
+        degradation?: Array<'native' | 'native_acp' | 'resource_link' | 'text_fallback' | 'paste' | 'upload'>;
+      }>;
+    };
     output?: { richContent?: boolean; mediaTypes?: Array<'text' | 'image' | 'audio' | 'video' | 'resource'> };
     controls?: { typedResults?: boolean };
   };