@adhdev/daemon-core 0.8.22 → 0.8.24

package/src/commands/handler.ts

@@ -441,6 +441,7 @@ export class DaemonCommandHandler implements CommandHelpers {
             case 'set_ide_extension': return Stream.handleSetIdeExtension(this, args);
 
             // ─── Extension Model / Mode Control (stream-commands.ts) ──────────
+            case 'invoke_provider_script': return Stream.handleProviderScript(this, args);
             case 'list_extension_models': return Stream.handleExtensionScript(this, args, 'listModels');
             case 'set_extension_model': return Stream.handleExtensionScript(this, args, 'setModel');
             case 'list_extension_modes': return Stream.handleExtensionScript(this, args, 'listModes');

package/src/commands/stream-commands.ts

@@ -96,7 +96,67 @@ export function handleSetProviderSetting(h: CommandHelpers, args: any): CommandR
 
 // ─── Extension Script Execution (Model/Mode) ─────
 
-export async function handleExtensionScript(h: CommandHelpers, args: any, scriptName: string): Promise<CommandResult> {
+function normalizeProviderScriptArgs(args: any): Record<string, any> {
+    const normalizedArgs = { ...(args || {}) };
+    for (const key of ['mode', 'model', 'message', 'action', 'button', 'text', 'sessionId', 'value']) {
+        if (key in normalizedArgs && !(key.toUpperCase() in normalizedArgs)) {
+            normalizedArgs[key.toUpperCase()] = normalizedArgs[key];
+        }
+    }
+    return normalizedArgs;
+}
+
+function parseScriptResult(result: unknown): { success: boolean; payload: any } {
+    if (typeof result === 'string') {
+        try {
+            const parsed = JSON.parse(result);
+            if (parsed && typeof parsed === 'object' && parsed.success === false) {
+                return { success: false, payload: parsed };
+            }
+            return { success: true, payload: parsed };
+        } catch {
+            return { success: true, payload: { result } };
+        }
+    }
+    if (result && typeof result === 'object' && (result as any).success === false) {
+        return { success: false, payload: result };
+    }
+    return { success: true, payload: result };
+}
+
+function getCliScriptCommand(payload: any): { type: string; text?: string } | null {
+    if (!payload || typeof payload !== 'object') return null;
+
+    if (typeof payload.sendMessage === 'string' && payload.sendMessage.trim()) {
+        return { type: 'send_message', text: payload.sendMessage.trim() };
+    }
+
+    const command = payload.command;
+    if (!command || typeof command !== 'object') return null;
+    if (command.type !== 'send_message') return null;
+
+    const text = typeof command.text === 'string'
+        ? command.text.trim()
+        : typeof command.message === 'string'
+            ? command.message.trim()
+            : '';
+    if (!text) return null;
+    return { type: 'send_message', text };
+}
+
+function applyProviderPatch(h: CommandHelpers, args: any, payload: any): void {
+    if (!payload || typeof payload !== 'object') return;
+    const targetSessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim() : '';
+    const targetSession = targetSessionId ? h.ctx.sessionRegistry?.get(targetSessionId) : undefined;
+    const instanceKey = targetSession?.instanceKey || targetSessionId;
+    if (!instanceKey) return;
+    h.ctx.instanceManager?.sendEvent(instanceKey, 'provider_state_patch', {
+        ...payload,
+        extensionType: targetSession?.transport === 'cdp-webview' ? targetSession.providerType : undefined,
+    });
+}
+
+async function executeProviderScript(h: CommandHelpers, args: any, scriptName: string): Promise<CommandResult> {
     const { agentType, ideType } = args || {};
     if (!agentType) return { success: false, error: 'agentType is required' };
 
@@ -115,15 +175,31 @@ export async function handleExtensionScript(h: CommandHelpers, args: any, script
         return { success: false, error: `Script '${actualScriptName}' not available for ${agentType}` };
     }
 
-    const scriptFn = provider.scripts[actualScriptName as keyof typeof provider.scripts] as Function;
-    // Normalize args: script placeholders use UPPERCASE (${MODE}, ${MODEL}, ${MESSAGE})
-    // but WebSocket args typically use lowercase. Add uppercase versions of common keys.
-    const normalizedArgs = { ...args };
-    for (const key of ['mode', 'model', 'message', 'action', 'button', 'text', 'sessionId']) {
-        if (key in normalizedArgs && !(key.toUpperCase() in normalizedArgs)) {
-            normalizedArgs[key.toUpperCase()] = normalizedArgs[key];
+    const normalizedArgs = normalizeProviderScriptArgs(args);
+
+    if (provider.category === 'cli') {
+        const adapter = h.getCliAdapter(args?.targetSessionId || agentType);
+        if (!adapter?.invokeScript) {
+            return { success: false, error: `CLI adapter does not support script '${actualScriptName}'` };
+        }
+        try {
+            const raw = await adapter.invokeScript(actualScriptName, normalizedArgs);
+            const parsed = parseScriptResult(raw);
+            if (!parsed.success) {
+                return { success: false, ...(parsed.payload || {}) };
+            }
+            const cliCommand = getCliScriptCommand(parsed.payload);
+            if (cliCommand?.type === 'send_message' && cliCommand.text) {
+                await adapter.sendMessage(cliCommand.text);
+            }
+            applyProviderPatch(h, args, parsed.payload);
+            return { success: true, ...(parsed.payload && typeof parsed.payload === 'object' ? parsed.payload : { result: parsed.payload }) };
+        } catch (e: any) {
+            return { success: false, error: `Script execution failed: ${e.message}` };
         }
     }
+
+    const scriptFn = provider.scripts[actualScriptName as keyof typeof provider.scripts] as Function;
     const scriptCode = scriptFn(normalizedArgs);
     if (!scriptCode) return { success: false, error: `Script '${actualScriptName}' returned null` };
 
@@ -187,17 +263,32 @@ export async function handleExtensionScript(h: CommandHelpers, args: any, script
         if (typeof result === 'string') {
             try {
                 const parsed = JSON.parse(result);
+                applyProviderPatch(h, args, parsed);
+                if (parsed && typeof parsed === 'object' && parsed.success === false) {
+                    return { success: false, ...parsed };
+                }
                 return { success: true, ...parsed };
             } catch {
                 return { success: true, result };
             }
         }
+        applyProviderPatch(h, args, result);
         return { success: true, result };
     } catch (e: any) {
         return { success: false, error: `Script execution failed: ${e.message}` };
     }
 }
 
+export async function handleExtensionScript(h: CommandHelpers, args: any, scriptName: string): Promise<CommandResult> {
+    return executeProviderScript(h, args, scriptName);
+}
+
+export async function handleProviderScript(h: CommandHelpers, args: any): Promise<CommandResult> {
+    const scriptName = typeof args?.scriptName === 'string' ? args.scriptName.trim() : '';
+    if (!scriptName) return { success: false, error: 'scriptName is required' };
+    return executeProviderScript(h, args, scriptName);
+}
+
 // ─── IDE Extension Settings (per-IDE on/off) ─────
 
 export function handleGetIdeExtensions(h: CommandHelpers, args: any): CommandResult {

package/src/config/config.d.ts

@@ -37,6 +37,7 @@ export interface ADHDevConfig {
     }>;
     disableUpstream?: boolean;
     providerDir?: string;
+    terminalSizingMode?: 'measured' | 'fit';
 }
 export declare function generateMachineId(): string;
 export declare function isStableMachineId(machineId?: string | null): boolean;

package/src/config/config.ts

@@ -78,6 +78,13 @@ export interface ADHDevConfig {
 
  // Optional custom provider directory for local development
     providerDir?: string;
+
+    /**
+     * Browser terminal sizing behavior for dashboard CLI panes.
+     * Default `measured` keeps terminal size daemon-authoritative.
+     * `fit` opt-in restores xterm fit-based sizing for advanced users.
+     */
+    terminalSizingMode?: 'measured' | 'fit';
 }
 
 const DEFAULT_CONFIG: ADHDevConfig = {
@@ -99,6 +106,7 @@ const DEFAULT_CONFIG: ADHDevConfig = {
     providerSettings: {},
     ideSettings: {},
     disableUpstream: false,
+    terminalSizingMode: 'measured',
 };
 
 const MACHINE_ID_PREFIX = 'mach_';
@@ -149,6 +157,7 @@ function normalizeConfig(raw: unknown): ADHDevConfig & { activeWorkspaceId?: str
         ideSettings: isPlainObject(parsed.ideSettings) ? parsed.ideSettings : {},
         disableUpstream: asBoolean(parsed.disableUpstream, DEFAULT_CONFIG.disableUpstream ?? false),
         providerDir: asOptionalString(parsed.providerDir),
+        terminalSizingMode: parsed.terminalSizingMode === 'fit' ? 'fit' : 'measured',
     };
 }
 

package/src/launch.ts

@@ -23,6 +23,7 @@ import * as path from 'path';
 import { detectIDEs } from './detection/ide-detector.js';
 import { IDEInfo } from './detection/ide-detector.js';
 import { ProviderLoader } from './providers/provider-loader.js';
+import type { ProviderModule } from './providers/contracts.js';
 
 // ─── Provider-based dynamic IDE infrastructure ────────────────
 // Reads cdpPorts, processNames from provider.js — only create provider.js to add new IDE
@@ -50,6 +51,26 @@ function getWinProcessNames(): Record<string, string[]> {
     return getProviderLoader().getWinProcessNames();
 }
 
+function getProviderMeta(ideId: string): ProviderModule | undefined {
+    return getProviderLoader().getMeta(ideId);
+}
+
+function getPreferredLaunchMethod(ideId: string, platform: NodeJS.Platform): 'auto' | 'cli' | 'app' {
+    const prefer = getProviderMeta(ideId)?.launch?.prefer;
+    const value = prefer?.[platform];
+    return value === 'cli' || value === 'app' || value === 'auto' ? value : 'auto';
+}
+
+function getCdpStartupTimeoutMs(ideId: string): number {
+    const value = getProviderMeta(ideId)?.launch?.cdpStartupTimeoutMs;
+    if (typeof value !== 'number' || !Number.isFinite(value)) return 15000;
+    return Math.max(1000, Math.floor(value));
+}
+
+function escapeForAppleScript(value: string): string {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
 // ─── Helpers ────────────────────────────────────
 
 /** Find available port (primary → secondary → sequential after) */
@@ -110,11 +131,11 @@ export async function killIdeProcess(ideId: string): Promise<boolean> {
         if (plat === 'darwin' && appName) {
  // macOS: graceful quit via osascript
             try {
-                execSync(`osascript -e 'tell application "${appName}" to quit' 2>/dev/null`, {
+                execSync(`osascript -e 'tell application "${escapeForAppleScript(appName)}" to quit' 2>/dev/null`, {
                     timeout: 5000,
                 });
             } catch {
-                try { execSync(`pkill -f "${appName}" 2>/dev/null`); } catch { }
+                try { execSync(`pkill -x "${appName}" 2>/dev/null`, { timeout: 5000 }); } catch { }
             }
         } else if (plat === 'win32' && winProcesses) {
  // Windows: taskkill for each process name
@@ -142,7 +163,7 @@ export async function killIdeProcess(ideId: string): Promise<boolean> {
 
  // Force terminate retry
         if (plat === 'darwin' && appName) {
-            try { execSync(`pkill -9 -f "${appName}" 2>/dev/null`); } catch { }
+            try { execSync(`pkill -9 -x "${appName}" 2>/dev/null`, { timeout: 5000 }); } catch { }
         } else if (plat === 'win32' && winProcesses) {
             for (const proc of winProcesses) {
                 try { execSync(`taskkill /IM "${proc}" /F 2>nul`); } catch { }
@@ -165,8 +186,23 @@ export function isIdeRunning(ideId: string): boolean {
         if (plat === 'darwin') {
             const appName = getMacAppIdentifiers()[ideId];
             if (!appName) return false;
-            const result = execSync(`pgrep -f "${appName}" 2>/dev/null`, { encoding: 'utf-8' });
-            return result.trim().length > 0;
+            try {
+                const result = execSync(`pgrep -x "${appName}" 2>/dev/null`, {
+                    encoding: 'utf-8',
+                    timeout: 3000,
+                });
+                return result.trim().length > 0;
+            } catch {
+                const result = execSync(
+                    `osascript -e 'tell application "System Events" to count (every process whose name is "${escapeForAppleScript(appName)}")'`,
+                    {
+                        encoding: 'utf-8',
+                        timeout: 3000,
+                        stdio: ['pipe', 'pipe', 'pipe'],
+                    },
+                );
+                return Number.parseInt(result.trim() || '0', 10) > 0;
+            }
         } else if (plat === 'win32') {
             const winProcesses = getWinProcessNames()[ideId];
             if (!winProcesses) return false;
@@ -350,7 +386,8 @@ export async function launchWithCdp(options: LaunchOptions = {}): Promise<Launch
 
  // Wait for CDP to enable (max 15 seconds)
         let cdpReady = false;
-        for (let i = 0; i < 30; i++) {
+        const waitDeadline = Date.now() + getCdpStartupTimeoutMs(targetIde.id);
+        while (Date.now() < waitDeadline) {
             await new Promise(r => setTimeout(r, 500));
             if (await isCdpActive(port)) {
                 cdpReady = true;
@@ -378,18 +415,27 @@ export async function launchWithCdp(options: LaunchOptions = {}): Promise<Launch
 
 async function launchMacOS(ide: IDEInfo, port: number, workspace?: string, newWindow?: boolean): Promise<void> {
     const appName = getMacAppIdentifiers()[ide.id];
+    const preferredMethod = getPreferredLaunchMethod(ide.id, 'darwin');
 
     const args = ['--remote-debugging-port=' + port];
     if (newWindow) args.push('--new-window');
     if (workspace) args.push(workspace);
 
-    if (appName) {
- // 'open -a' execution (ensures GUI session)
-        const openArgs = ['-a', appName, '--args', ...args];
-        spawn('open', openArgs, { detached: true, stdio: 'ignore' }).unref();
-    } else if (ide.cliCommand) {
+    const canUseCli = !!ide.cliCommand;
+    const canUseAppLauncher = !!appName;
+    const useAppLauncher = preferredMethod === 'app'
+        ? canUseAppLauncher
+        : preferredMethod === 'cli'
+            ? false
+            : !canUseCli && canUseAppLauncher;
+
+    if (!useAppLauncher && ide.cliCommand) {
  // CLI based execute
         spawn(ide.cliCommand, args, { detached: true, stdio: 'ignore' }).unref();
+    } else if (appName) {
+ // Fallback to `open -a` when no CLI wrapper is available or the provider prefers it.
+        const openArgs = ['-a', appName, '--args', ...args];
+        spawn('open', openArgs, { detached: true, stdio: 'ignore' }).unref();
     } else {
         throw new Error(`No app identifier or CLI for ${ide.displayName}`);
     }

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

@@ -16,9 +16,10 @@ import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
 import type { CliProviderModule } from '../cli-adapters/provider-cli-adapter.js';
 import type { PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 import { StatusMonitor } from './status-monitor.js';
-import { ChatHistoryWriter } from '../config/chat-history.js';
+import { ChatHistoryWriter, readChatHistory } from '../config/chat-history.js';
 import { LOG } from '../logging/logger.js';
 import type { ChatMessage } from '../types.js';
+import { extractProviderControlValues, normalizeProviderEffects } from './control-effects.js';
 
 let CachedDatabaseSync: (new (path: string, options?: { readOnly?: boolean }) => {
     prepare(sql: string): { get(...params: Array<string | number>): unknown };
@@ -54,6 +55,8 @@ export class CliProviderInstance implements ProviderInstance {
     private generatingDebounceTimer: NodeJS.Timeout | null = null;
     private generatingDebouncePending: { chatTitle: string; timestamp: number } | null = null;
     private lastApprovalEventAt = 0;
+    private controlValues: Record<string, string | number | boolean> = {};
+    private appliedEffectKeys = new Set<string>();
     private historyWriter: ChatHistoryWriter;
     private runtimeMessages: Array<{ key: string; message: ChatMessage }> = [];
     readonly instanceId: string;
@@ -106,6 +109,7 @@ export class CliProviderInstance implements ProviderInstance {
     async init(context: InstanceContext): Promise<void> {
         this.context = context;
         this.settings = context.settings || {};
+        this.adapter.updateRuntimeSettings?.(this.settings);
         this.monitor.updateConfig({
             approvalAlert: this.settings.approvalAlert !== false,
             longGeneratingAlert: this.settings.longGeneratingAlert !== false,
@@ -129,6 +133,21 @@ export class CliProviderInstance implements ProviderInstance {
 
  // PTY spawn
         await this.adapter.spawn();
+        if (this.providerSessionId) {
+            const restoredHistory = readChatHistory(this.type, 0, 200, this.providerSessionId);
+            if (restoredHistory.messages.length > 0) {
+                this.adapter.seedCommittedMessages(
+                    restoredHistory.messages.map((message) => ({
+                        role: message.role,
+                        content: message.content,
+                        timestamp: message.receivedAt,
+                        receivedAt: message.receivedAt,
+                        kind: message.kind,
+                        senderName: message.senderName,
+                    })),
+                );
+            }
+        }
         if (this.providerSessionId && this.launchMode === 'resume') {
             const resumedAt = Date.now();
             this.historyWriter.appendSystemMarker(
@@ -228,6 +247,12 @@ export class CliProviderInstance implements ProviderInstance {
         }
         const runtime = this.adapter.getRuntimeMetadata();
         const parsedMessages = Array.isArray(parsedStatus?.messages) ? parsedStatus.messages : [];
+        const controlValues = extractProviderControlValues(this.provider.controls, parsedStatus);
+        if (controlValues) {
+            this.controlValues = controlValues;
+        } else if (Object.keys(this.controlValues).length > 0) {
+            this.controlValues = {};
+        }
         const mergedMessages = this.mergeConversationMessages(parsedMessages);
 
         const dirName = this.workingDir.split('/').filter(Boolean).pop() || 'session';
@@ -251,6 +276,8 @@ export class CliProviderInstance implements ProviderInstance {
             }
         }
 
+        this.applyProviderResponse(parsedStatus, { phase: 'immediate' });
+
         return {
             type: this.type,
             name: this.provider.name,
@@ -280,7 +307,7 @@ export class CliProviderInstance implements ProviderInstance {
                 attachedClients: runtime.attachedClients || [],
             } : undefined,
             resume: this.provider.resume,
-            controlValues: undefined, // CLI controls not yet wired from stream
+            controlValues: this.controlValues,
             providerControls: this.provider.controls as any,
         };
     }
@@ -294,6 +321,16 @@ export class CliProviderInstance implements ProviderInstance {
         return this.presentationMode;
     }
 
+    updateSettings(newSettings: Record<string, any>): void {
+        this.settings = { ...newSettings };
+        this.adapter.updateRuntimeSettings?.(this.settings);
+        this.monitor.updateConfig({
+            approvalAlert: this.settings.approvalAlert !== false,
+            longGeneratingAlert: this.settings.longGeneratingAlert !== false,
+            longGeneratingThresholdSec: this.settings.longGeneratingThresholdSec || 180,
+        });
+    }
+
     onEvent(event: string, data?: any): void {
         if (event === 'send_message' && data?.text) {
             void this.adapter.sendMessage(data.text).catch((e: any) => {
@@ -305,12 +342,15 @@ export class CliProviderInstance implements ProviderInstance {
             void this.adapter.resolveAction(data).catch((e: any) => {
                 LOG.warn('CLI', `[${this.type}] resolve_action failed: ${e?.message || e}`);
             });
+        } else if (event === 'provider_state_patch' && data && typeof data === 'object') {
+            this.applyProviderResponse(data, { phase: 'immediate' });
         }
     }
 
     dispose(): void {
         this.adapter.shutdown();
         this.monitor.reset();
+        this.appliedEffectKeys.clear();
     }
 
     private completedDebounceTimer: NodeJS.Timeout | null = null;
@@ -319,6 +359,7 @@ export class CliProviderInstance implements ProviderInstance {
     private detectStatusTransition(): void {
         const now = Date.now();
         const adapterStatus = this.adapter.getStatus();
+        const parsedStatus = this.adapter.getScriptParsedStatus?.() || null;
         const newStatus = adapterStatus.status;
         const dirName = this.workingDir.split('/').filter(Boolean).pop() || 'session';
         const chatTitle = `${this.provider.name} · ${dirName}`;
@@ -327,6 +368,7 @@ export class CliProviderInstance implements ProviderInstance {
             ? `${partial || ''}::${adapterStatus.messages.at(-1)?.content || ''}`.slice(-2000)
             : undefined;
 
+        const previousStatus = this.lastStatus;
         if (newStatus !== this.lastStatus) {
             LOG.info('CLI', `[${this.type}] status: ${this.lastStatus} → ${newStatus}`);
             if (this.lastStatus === 'idle' && newStatus === 'generating') {
@@ -411,6 +453,12 @@ export class CliProviderInstance implements ProviderInstance {
             this.lastStatus = newStatus;
         }
 
+        this.applyProviderResponse(parsedStatus, {
+            phase: (newStatus === 'idle' && (previousStatus === 'generating' || previousStatus === 'waiting_approval'))
+                ? 'turn_completed'
+                : 'immediate',
+        });
+
  // Monitor check (cooldown based notification, IDE/CLI common)
         const agentKey = `${this.type}:cli`;
         const monitorEvents = this.monitor.check(agentKey, newStatus, now, progressFingerprint);
@@ -431,6 +479,104 @@ export class CliProviderInstance implements ProviderInstance {
         return events;
     }
 
+    private applyProviderResponse(data: any, options: { phase: 'immediate' | 'turn_completed' }): void {
+        if (!data || typeof data !== 'object') return;
+
+        const controlValues = extractProviderControlValues(this.provider.controls, data);
+        if (controlValues) {
+            this.controlValues = { ...this.controlValues, ...controlValues };
+        }
+
+        const effects = normalizeProviderEffects(data);
+        for (const effect of effects) {
+            const effectWhen = effect.when || 'immediate';
+            if (effectWhen === 'turn_completed' && options.phase !== 'turn_completed') continue;
+            if (effectWhen === 'immediate' && options.phase === 'turn_completed') continue;
+
+            const effectKey = this.getEffectDedupKey(effect);
+            if (this.appliedEffectKeys.has(effectKey)) continue;
+            this.appliedEffectKeys.add(effectKey);
+
+            if (effect.persist !== false) {
+                const persisted = this.getPersistedEffectContent(effect);
+                if (persisted) this.appendRuntimeSystemMessage(persisted, effectKey);
+            }
+
+            if (effect.type === 'message' && effect.message) {
+                const content = typeof effect.message.content === 'string'
+                    ? effect.message.content
+                    : JSON.stringify(effect.message.content);
+                this.pushEvent({
+                    event: 'provider:message',
+                    timestamp: Date.now(),
+                    content,
+                    role: effect.message.role || 'system',
+                    kind: effect.message.kind,
+                    senderName: effect.message.senderName,
+                });
+            } else if (effect.type === 'toast' && effect.toast) {
+                this.pushEvent({
+                    event: 'provider:toast',
+                    effectId: effect.id || effectKey,
+                    timestamp: Date.now(),
+                    message: effect.toast.message,
+                    level: effect.toast.level || 'info',
+                });
+            } else if (effect.type === 'notification' && effect.notification) {
+                this.pushEvent({
+                    event: 'provider:notification',
+                    effectId: effect.id || effectKey,
+                    timestamp: Date.now(),
+                    title: effect.notification.title,
+                    message: effect.notification.body,
+                    content: typeof effect.notification.bubbleContent === 'string'
+                        ? effect.notification.bubbleContent
+                        : effect.notification.body,
+                    level: effect.notification.level || 'info',
+                    channels: effect.notification.channels || ['toast'],
+                    preferenceKey: effect.notification.preferenceKey,
+                });
+            }
+        }
+
+        if (this.appliedEffectKeys.size > 200) {
+            this.appliedEffectKeys = new Set(Array.from(this.appliedEffectKeys).slice(-100));
+        }
+    }
+
+    private getEffectDedupKey(effect: { id?: string; type: string; message?: { content?: unknown }; toast?: { message?: string }; notification?: { title?: string; body?: string } }): string {
+        if (effect.id) return `provider_effect:${effect.id}`;
+        if (effect.type === 'message') {
+            const content = typeof effect.message?.content === 'string'
+                ? effect.message.content
+                : JSON.stringify(effect.message?.content || '');
+            return `provider_effect:message:${content}`;
+        }
+        if (effect.type === 'notification') {
+            return `provider_effect:notification:${effect.notification?.title || ''}:${effect.notification?.body || ''}`;
+        }
+        return `provider_effect:toast:${effect.toast?.message || ''}`;
+    }
+
+    private getPersistedEffectContent(effect: { type: string; message?: { content?: unknown }; toast?: { message?: string }; notification?: { title?: string; body?: string; bubbleContent?: unknown } }): string | null {
+        if (effect.type === 'message') {
+            return typeof effect.message?.content === 'string'
+                ? effect.message.content
+                : JSON.stringify(effect.message?.content || '');
+        }
+        if (effect.type === 'toast') {
+            return effect.toast?.message || null;
+        }
+        if (effect.type === 'notification') {
+            if (typeof effect.notification?.bubbleContent === 'string') return effect.notification.bubbleContent;
+            if (typeof effect.notification?.title === 'string' && effect.notification.title.trim()) {
+                return `${effect.notification.title}\n${effect.notification.body || ''}`.trim();
+            }
+            return effect.notification?.body || null;
+        }
+        return null;
+    }
+
  // ─── Adapter access (backward compat) ──────────────────
 
     getAdapter(): ProviderCliAdapter {

package/src/providers/contracts.ts

@@ -26,6 +26,10 @@ export interface ReadChatResult {
   inputContent?: string;
   model?: string;
   autoApprove?: string;
+  /** Explicit dynamic control values returned by the provider */
+  controlValues?: Record<string, string | number | boolean>;
+  /** Provider-driven UI effects derived from chat state */
+  effects?: ProviderEffect[];
 }
 
 import type { ChatMessage } from '../types.js';
@@ -46,6 +50,43 @@ export interface ModalInfo {
   height?: number;
 }
 
+export interface ProviderEffectMessage {
+  role?: 'system' | 'assistant' | 'user';
+  content: string | ContentBlock[];
+  kind?: string;
+  senderName?: string;
+}
+
+export interface ProviderEffectToast {
+  level?: 'info' | 'success' | 'warning';
+  message: string;
+}
+
+export type ProviderNotificationPreferenceKey = 'disconnect' | 'completion' | 'approval' | 'browser';
+export type ProviderNotificationChannel = 'bubble' | 'toast' | 'browser';
+
+export interface ProviderEffectNotification {
+  title?: string;
+  body: string;
+  level?: 'info' | 'success' | 'warning';
+  channels?: ProviderNotificationChannel[];
+  preferenceKey?: ProviderNotificationPreferenceKey;
+  bubbleContent?: string | ContentBlock[];
+}
+
+export interface ProviderEffect {
+  type: 'message' | 'toast' | 'notification';
+  /** Stable dedup key; falls back to a content hash when omitted */
+  id?: string;
+  /** Default immediate. turn_completed fires only on generating/waiting -> idle transitions. */
+  when?: 'immediate' | 'turn_completed';
+  /** Default true. False keeps the effect UI-only. */
+  persist?: boolean;
+  message?: ProviderEffectMessage;
+  toast?: ProviderEffectToast;
+  notification?: ProviderEffectNotification;
+}
+
 // ─── Rich Content Types (ACP Standard) ─────────────────
 // Based on ACP SDK v0.16.1 schema types.
 // All provider categories (ACP, IDE, Extension, CLI) use these as output standard.
@@ -290,13 +331,35 @@ export interface ProviderModule {
   versionCommand?: string;
  /** Versions tested by provider maintainer (informational) */
   testedVersions?: string[];
- /** Per-OS process names — used by launch.ts to detect/kill IDE processes */
+  /** Per-OS process names — used by launch.ts to detect/kill IDE processes */
   processNames?: {
     darwin?: string;
     win32?: string[];
     linux?: string[];
     [key: string]: string | string[] | undefined;
   };
+  /**
+   * IDE launch preferences.
+   * Lets each provider choose how its GUI app should be started per platform.
+   */
+  launch?: {
+    /**
+     * Preferred launch method by platform.
+     * - 'cli': use the IDE CLI wrapper/binary
+     * - 'app': use platform app launcher (e.g. `open -a` on macOS)
+     * - 'auto': let core choose a sensible default
+     */
+    prefer?: {
+      darwin?: 'auto' | 'cli' | 'app';
+      win32?: 'auto' | 'cli' | 'app';
+      linux?: 'auto' | 'cli' | 'app';
+      [key: string]: 'auto' | 'cli' | 'app' | undefined;
+    };
+    /**
+     * Override how long core waits for CDP to come up after launch.
+     */
+    cdpStartupTimeoutMs?: number;
+  };
  /** Per-OS install paths — used by detector.ts to detect IDE installation */
   paths?: {
     darwin?: string[];
@@ -580,7 +643,7 @@ export interface ProviderSettingSchema extends ProviderSettingDef {
  * - 'slider'  — numeric range (temperature: 0–2)
  * - 'action'  — one-shot button (show usage, restart, clear context)
  */
-export type ProviderControlType = 'select' | 'toggle' | 'cycle' | 'slider' | 'action';
+export type ProviderControlType = 'select' | 'toggle' | 'cycle' | 'slider' | 'action' | 'display';
 
 /**
  * Where the control appears in the chat UI: