@adhdev/daemon-core 0.8.49 → 0.8.50

package/dist/logging/command-log.d.ts

@@ -13,6 +13,7 @@ export interface CommandLogEntry {
     ts: string;
     cmd: string;
     source: 'ws' | 'p2p' | 'ext' | 'api' | 'standalone' | 'unknown';
+    interactionId?: string;
     args?: Record<string, unknown>;
     success?: boolean;
     error?: string;

package/dist/logging/debug-config.d.ts

@@ -0,0 +1,21 @@
+import type { LogLevel } from './logger.js';
+export interface DebugRuntimeOptions {
+    dev?: boolean;
+    logLevel?: LogLevel;
+    trace?: boolean;
+    traceContent?: boolean;
+    traceBufferSize?: number;
+    traceCategories?: string[];
+}
+export interface DebugRuntimeConfig {
+    logLevel: LogLevel;
+    collectDebugTrace: boolean;
+    traceContent: boolean;
+    traceBufferSize: number;
+    traceCategories: string[];
+}
+export declare function resolveDebugRuntimeConfig(options?: DebugRuntimeOptions): DebugRuntimeConfig;
+export declare function setDebugRuntimeConfig(config: DebugRuntimeConfig): void;
+export declare function getDebugRuntimeConfig(): DebugRuntimeConfig;
+export declare function resetDebugRuntimeConfig(): void;
+export declare function shouldCollectTraceCategory(category?: string | null): boolean;

package/dist/logging/debug-trace.d.ts

@@ -0,0 +1,35 @@
+export type DebugTraceLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface DebugTraceEvent {
+    interactionId?: string;
+    category: string;
+    stage: string;
+    level: DebugTraceLevel;
+    sessionId?: string;
+    providerType?: string;
+    payload?: Record<string, unknown>;
+}
+export interface DebugTraceEntry extends DebugTraceEvent {
+    id: string;
+    ts: number;
+}
+export interface DebugTraceStoreOptions {
+    enabled: boolean;
+    capacity: number;
+}
+export interface DebugTraceQuery {
+    interactionId?: string;
+    category?: string;
+    limit?: number;
+}
+export interface DebugTraceStore {
+    record(event: DebugTraceEvent): DebugTraceEntry | null;
+    list(query?: DebugTraceQuery): DebugTraceEntry[];
+    clear(): void;
+}
+export declare function sanitizeTracePayload(payload?: Record<string, unknown>): Record<string, unknown>;
+export declare function createDebugTraceStore(options: DebugTraceStoreOptions): DebugTraceStore;
+export declare function configureDebugTraceStore(): void;
+export declare function recordDebugTrace(event: DebugTraceEvent): DebugTraceEntry | null;
+export declare function getRecentDebugTrace(query?: DebugTraceQuery): DebugTraceEntry[];
+export declare function clearDebugTrace(): void;
+export declare function createInteractionId(prefix?: string): string;

package/dist/session-host/app-name.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_SESSION_HOST_APP_NAME = "adhdev";
+export declare const DEFAULT_STANDALONE_SESSION_HOST_APP_NAME = "adhdev-standalone";
+export declare function resolveSessionHostAppName(options?: {
+    standalone?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): string;

package/dist/shared-types.d.ts

@@ -138,6 +138,7 @@ export interface SessionChatTailUpdate extends ReadChatSyncResult {
     key: string;
     sessionId: string;
     historySessionId?: string;
+    interactionId?: string;
     seq: number;
     timestamp: number;
 }
@@ -163,6 +164,7 @@ export interface SessionModalUpdate {
     title?: string;
     modalMessage?: string;
     modalButtons?: string[];
+    interactionId?: string;
     seq: number;
     timestamp: number;
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/session-host-core",
-  "version": "0.8.49",
+  "version": "0.8.50",
   "description": "ADHDev local session host core — session registry, protocol, buffers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.8.49",
+  "version": "0.8.50",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/commands/chat-commands.ts

@@ -9,6 +9,7 @@ import { flattenContent, type ProviderModule, type ProviderScripts } from '../pr
 import type { ProviderInstance } from '../providers/provider-instance.js';
 import { readChatHistory } from '../config/chat-history.js';
 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';
 
@@ -103,6 +104,34 @@ function getHistorySessionId(h: CommandHelpers, args: any): string | undefined {
     return providerSessionId || targetSessionId;
 }
 
+function getInteractionId(args: any): string | undefined {
+    return typeof args?._interactionId === 'string' && args._interactionId.trim()
+        ? args._interactionId.trim()
+        : undefined;
+}
+
+function traceProviderEvent(
+    args: any,
+    category: 'provider' | 'parser',
+    stage: string,
+    options: {
+        h: CommandHelpers;
+        provider?: ProviderModule;
+        payload?: Record<string, unknown>;
+        level?: 'debug' | 'info' | 'warn' | 'error';
+    },
+): void {
+    recordDebugTrace({
+        interactionId: getInteractionId(args),
+        category,
+        stage,
+        level: options.level || 'info',
+        sessionId: typeof args?.targetSessionId === 'string' ? args.targetSessionId : options.h.currentSession?.sessionId,
+        providerType: options.provider?.type || options.h.currentProviderType || options.h.currentSession?.providerType,
+        payload: options.payload,
+    });
+}
+
 function callLegacyTextScript(script: ProviderScripts[keyof ProviderScripts] | undefined, text: string): string | null {
     if (typeof script !== 'function') return null;
     return (script as LegacyStringScript)(text);
@@ -392,6 +421,16 @@ export async function handleReadChat(h: CommandHelpers, args: any): Promise<Comm
                 if (typeof parsed === 'string') { try { parsed = JSON.parse(parsed); } catch { } }
                 if (parsed && typeof parsed === 'object') {
                     _log(`Extension OK: ${parsed.messages?.length || 0} msgs`);
+                    traceProviderEvent(args, 'provider', 'extension.read_chat.success', {
+                        h,
+                        provider,
+                        payload: {
+                            method: 'evaluateProviderScript',
+                            result: evalResult.result,
+                            parsed,
+                            messageCount: Array.isArray(parsed.messages) ? parsed.messages.length : 0,
+                        },
+                    });
                     h.historyWriter.appendNewMessages(
                         provider?.type || 'unknown_extension',
                         toHistoryPersistedMessages(normalizeReadChatMessages(parsed)),
@@ -404,6 +443,12 @@ export async function handleReadChat(h: CommandHelpers, args: any): Promise<Comm
             }
         } catch (e: any) {
             _log(`Extension error: ${e.message}`);
+            traceProviderEvent(args, 'provider', 'extension.read_chat.error', {
+                h,
+                provider,
+                level: 'warn',
+                payload: { method: 'evaluateProviderScript', error: e.message },
+            });
         }
         // Alternative: AgentStreamManager (script fail when)
         if (h.agentStream) {
@@ -471,22 +516,40 @@ export async function handleReadChat(h: CommandHelpers, args: any): Promise<Comm
     const script = h.getProviderScript('readChat') || h.getProviderScript('read_chat');
     if (script) {
         try {
-            const result = await cdp.evaluate(script, 50000);
-            let parsed: any = result;
-            if (typeof parsed === 'string') { try { parsed = JSON.parse(parsed); } catch { } }
-            if (parsed && typeof parsed === 'object' && parsed.messages?.length > 0) {
-                _log(`OK: ${parsed.messages?.length} msgs`);
-                h.historyWriter.appendNewMessages(
-                    provider?.type || getCurrentProviderType(h, 'unknown_ide'),
-                    toHistoryPersistedMessages(normalizeReadChatMessages(parsed)),
-                    parsed.title,
-                    args?.targetSessionId,
-                    historySessionId,
-                );
-                return buildReadChatCommandResult(parsed, args);
+            const evalResult = await h.evaluateProviderScript('readChat', undefined, 50000);
+            if (evalResult?.result) {
+                let parsed: any = evalResult.result;
+                if (typeof parsed === 'string') { try { parsed = JSON.parse(parsed); } catch { } }
+                if (parsed && typeof parsed === 'object' && parsed.messages?.length > 0) {
+                    _log(`OK: ${parsed.messages?.length} msgs`);
+                    traceProviderEvent(args, 'provider', 'ide.read_chat.success', {
+                        h,
+                        provider,
+                        payload: {
+                            method: 'evaluate',
+                            result: evalResult.result,
+                            parsed,
+                            messageCount: Array.isArray(parsed.messages) ? parsed.messages.length : 0,
+                        },
+                    });
+                    h.historyWriter.appendNewMessages(
+                        provider?.type || getCurrentProviderType(h, 'unknown_ide'),
+                        toHistoryPersistedMessages(normalizeReadChatMessages(parsed)),
+                        parsed.title,
+                        args?.targetSessionId,
+                        historySessionId,
+                    );
+                    return buildReadChatCommandResult(parsed, args);
+                }
             }
         } catch (e: any) {
             LOG.info('Command', `[read_chat] Script error: ${e.message}`);
+            traceProviderEvent(args, 'provider', 'ide.read_chat.error', {
+                h,
+                provider,
+                level: 'warn',
+                payload: { method: 'evaluate', error: e.message },
+            });
         }
     }
 

package/src/commands/router.ts

@@ -30,6 +30,7 @@ import { LOG } from '../logging/logger.js';
 import { logCommand } from '../logging/command-log.js';
 import type { CommandLogEntry } from '../logging/command-log.js';
 import { getRecentLogs, LOG_PATH } from '../logging/logger.js';
+import { createInteractionId, getRecentDebugTrace, recordDebugTrace } from '../logging/debug-trace.js';
 import { buildSessionEntries } from '../status/builders.js';
 import { buildMachineInfo, buildStatusSnapshot } from '../status/snapshot.js';
 import { getSessionCompletionMarker } from '../status/snapshot.js';
@@ -104,6 +105,14 @@ function normalizeCommandSource(source: string): CommandLogEntry['source'] {
     }
 }
 
+function normalizeCommandArgsWithInteractionId(args: any): Record<string, unknown> {
+    const base = args && typeof args === 'object' ? { ...args } : {};
+    if (typeof base._interactionId !== 'string' || !String(base._interactionId).trim()) {
+        base._interactionId = createInteractionId();
+    }
+    return base;
+}
+
 function toHostedCliRuntimeDescriptor(record: any): HostedCliRuntimeDescriptor | null {
     if (!record || typeof record !== 'object') return null;
     const runtimeId = typeof record.sessionId === 'string' ? record.sessionId : '';
@@ -149,18 +158,42 @@ export class DaemonCommandRouter {
     async execute(cmd: string, args: any, source: string = 'unknown'): Promise<CommandRouterResult> {
         const cmdStart = Date.now();
         const logSource = normalizeCommandSource(source);
+        const normalizedArgs = normalizeCommandArgsWithInteractionId(args);
+        const interactionId = typeof normalizedArgs._interactionId === 'string' ? normalizedArgs._interactionId : undefined;
+
+        recordDebugTrace({
+            interactionId,
+            category: 'command',
+            stage: 'received',
+            level: 'info',
+            payload: { cmd, source: logSource },
+        });
 
         try {
             // 1. Try daemon-level command
-            const daemonResult = await this.executeDaemonCommand(cmd, args);
+            const daemonResult = await this.executeDaemonCommand(cmd, normalizedArgs);
             if (daemonResult) {
-                logCommand({ ts: new Date().toISOString(), cmd, source: logSource, args, success: daemonResult.success, durationMs: Date.now() - cmdStart });
+                logCommand({ ts: new Date().toISOString(), cmd, source: logSource, interactionId, args: normalizedArgs, success: daemonResult.success, durationMs: Date.now() - cmdStart });
+                recordDebugTrace({
+                    interactionId,
+                    category: 'command',
+                    stage: 'completed',
+                    level: daemonResult.success ? 'info' : 'warn',
+                    payload: { cmd, source: logSource, success: daemonResult.success, durationMs: Date.now() - cmdStart },
+                });
                 return daemonResult;
             }
 
             // 2. Delegate to DaemonCommandHandler
-            const handlerResult = await this.deps.commandHandler.handle(cmd, args);
-            logCommand({ ts: new Date().toISOString(), cmd, source: logSource, args, success: handlerResult.success, durationMs: Date.now() - cmdStart });
+            const handlerResult = await this.deps.commandHandler.handle(cmd, normalizedArgs);
+            logCommand({ ts: new Date().toISOString(), cmd, source: logSource, interactionId, args: normalizedArgs, success: handlerResult.success, durationMs: Date.now() - cmdStart });
+            recordDebugTrace({
+                interactionId,
+                category: 'command',
+                stage: 'completed',
+                level: handlerResult.success ? 'info' : 'warn',
+                payload: { cmd, source: logSource, success: handlerResult.success, durationMs: Date.now() - cmdStart },
+            });
 
             // 3. Post-chat command callback
             if (CHAT_COMMANDS.includes(cmd) && this.deps.onPostChatCommand) {
@@ -169,7 +202,14 @@ export class DaemonCommandRouter {
 
             return handlerResult;
         } catch (e: any) {
-            logCommand({ ts: new Date().toISOString(), cmd, source: logSource, args, success: false, error: e.message, durationMs: Date.now() - cmdStart });
+            logCommand({ ts: new Date().toISOString(), cmd, source: logSource, interactionId, args: normalizedArgs, success: false, error: e.message, durationMs: Date.now() - cmdStart });
+            recordDebugTrace({
+                interactionId,
+                category: 'command',
+                stage: 'failed',
+                level: 'error',
+                payload: { cmd, source: logSource, error: e?.message || String(e), durationMs: Date.now() - cmdStart },
+            });
             throw e;
         }
     }
@@ -218,6 +258,16 @@ export class DaemonCommandRouter {
                 }
             }
 
+            case 'get_debug_trace': {
+                const count = parseInt(args?.count) || parseInt(args?.limit) || 100;
+                const sinceTs = Number(args?.since) || 0;
+                const interactionId = typeof args?.interactionId === 'string' ? args.interactionId : undefined;
+                const category = typeof args?.category === 'string' ? args.category : undefined;
+                const trace = getRecentDebugTrace({ interactionId, category, limit: count })
+                    .filter((entry) => !sinceTs || entry.ts > sinceTs);
+                return { success: true, trace, count: trace.length };
+            }
+
             case 'session_host_get_diagnostics': {
                 if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
                 const diagnostics = await this.deps.sessionHostControl.getDiagnostics({

package/src/index.ts

@@ -151,6 +151,23 @@ export {
     getCurrentDaemonLogPath,
 } from './logging/logger.js';
 export type { ScopedLogger, LogLevel, LogEntry } from './logging/logger.js';
+export {
+    resolveDebugRuntimeConfig,
+    setDebugRuntimeConfig,
+    getDebugRuntimeConfig,
+    resetDebugRuntimeConfig,
+    shouldCollectTraceCategory,
+} from './logging/debug-config.js';
+export type { DebugRuntimeOptions, DebugRuntimeConfig } from './logging/debug-config.js';
+export {
+    createDebugTraceStore,
+    configureDebugTraceStore,
+    recordDebugTrace,
+    getRecentDebugTrace,
+    clearDebugTrace,
+    createInteractionId,
+} from './logging/debug-trace.js';
+export type { DebugTraceEvent, DebugTraceEntry, DebugTraceQuery, DebugTraceStore, DebugTraceLevel } from './logging/debug-trace.js';
 export { logCommand, getRecentCommands } from './logging/command-log.js';
 
 // ── CLI Management ──
@@ -191,6 +208,11 @@ export { NodePtyTransportFactory } from './cli-adapters/pty-transport.js';
 export type { PtyRuntimeTransport, PtyTransportFactory, PtySpawnOptions } from './cli-adapters/pty-transport.js';
 export { SessionHostPtyTransportFactory } from './cli-adapters/session-host-transport.js';
 export type { HostedCliRuntimeDescriptor, CliTransportFactoryParams } from './commands/cli-manager.js';
+export {
+  DEFAULT_SESSION_HOST_APP_NAME,
+  DEFAULT_STANDALONE_SESSION_HOST_APP_NAME,
+  resolveSessionHostAppName,
+} from './session-host/app-name.js';
 export { ensureSessionHostReady, listHostedCliRuntimes } from './session-host/runtime-support.js';
 export type { SessionHostEndpoint } from '@adhdev/session-host-core';
 

package/src/logging/command-log.ts

@@ -31,6 +31,7 @@ export interface CommandLogEntry {
     ts: string;           // ISO timestamp
     cmd: string;          // command name
     source: 'ws' | 'p2p' | 'ext' | 'api' | 'standalone' | 'unknown';  // where it came from
+    interactionId?: string;
     args?: Record<string, unknown>;  // command arguments (sensitive values masked)
     success?: boolean;    // result
     error?: string;       // error message if failed
@@ -136,6 +137,7 @@ export function logCommand(entry: CommandLogEntry): void {
             ts: entry.ts,
             cmd: entry.cmd,
             src: entry.source,
+            ...(entry.interactionId ? { interactionId: entry.interactionId } : {}),
             ...(entry.args ? { args: maskArgs(entry.args) } : {}),
             ...(entry.success !== undefined ? { ok: entry.success } : {}),
             ...(entry.error ? { err: entry.error } : {}),
@@ -161,6 +163,7 @@ export function getRecentCommands(count = 50): CommandLogEntry[] {
                     ts: parsed.ts,
                     cmd: parsed.cmd,
                     source: parsed.src,
+                    interactionId: parsed.interactionId,
                     args: parsed.args,
                     success: parsed.ok,
                     error: parsed.err,

package/src/logging/debug-config.ts

@@ -0,0 +1,75 @@
+import type { LogLevel } from './logger.js'
+
+export interface DebugRuntimeOptions {
+  dev?: boolean
+  logLevel?: LogLevel
+  trace?: boolean
+  traceContent?: boolean
+  traceBufferSize?: number
+  traceCategories?: string[]
+}
+
+export interface DebugRuntimeConfig {
+  logLevel: LogLevel
+  collectDebugTrace: boolean
+  traceContent: boolean
+  traceBufferSize: number
+  traceCategories: string[]
+}
+
+const NORMAL_TRACE_BUFFER_SIZE = 200
+const DEV_TRACE_BUFFER_SIZE = 1000
+
+const DEFAULT_CONFIG: DebugRuntimeConfig = {
+  logLevel: 'info',
+  collectDebugTrace: false,
+  traceContent: false,
+  traceBufferSize: NORMAL_TRACE_BUFFER_SIZE,
+  traceCategories: [],
+}
+
+let currentConfig: DebugRuntimeConfig = { ...DEFAULT_CONFIG }
+
+function normalizeCategories(categories?: string[]): string[] {
+  if (!Array.isArray(categories)) return []
+  return categories
+    .map((category) => String(category || '').trim())
+    .filter(Boolean)
+}
+
+export function resolveDebugRuntimeConfig(options: DebugRuntimeOptions = {}): DebugRuntimeConfig {
+  const dev = options.dev === true
+  return {
+    logLevel: options.logLevel || (dev ? 'debug' : DEFAULT_CONFIG.logLevel),
+    collectDebugTrace: typeof options.trace === 'boolean' ? options.trace : dev,
+    traceContent: options.traceContent === true,
+    traceBufferSize: Number.isFinite(options.traceBufferSize)
+      ? Math.max(10, Math.floor(options.traceBufferSize as number))
+      : (dev ? DEV_TRACE_BUFFER_SIZE : DEFAULT_CONFIG.traceBufferSize),
+    traceCategories: normalizeCategories(options.traceCategories),
+  }
+}
+
+export function setDebugRuntimeConfig(config: DebugRuntimeConfig): void {
+  currentConfig = {
+    ...config,
+    traceCategories: normalizeCategories(config.traceCategories),
+    traceBufferSize: Math.max(10, Math.floor(config.traceBufferSize || DEFAULT_CONFIG.traceBufferSize)),
+  }
+}
+
+export function getDebugRuntimeConfig(): DebugRuntimeConfig {
+  return { ...currentConfig, traceCategories: [...currentConfig.traceCategories] }
+}
+
+export function resetDebugRuntimeConfig(): void {
+  currentConfig = { ...DEFAULT_CONFIG }
+}
+
+export function shouldCollectTraceCategory(category?: string | null): boolean {
+  const config = currentConfig
+  if (!config.collectDebugTrace) return false
+  if (!category) return true
+  if (config.traceCategories.length === 0) return true
+  return config.traceCategories.includes(category)
+}

package/src/logging/debug-trace.ts

@@ -0,0 +1,130 @@
+import { getDebugRuntimeConfig, shouldCollectTraceCategory } from './debug-config.js'
+
+export type DebugTraceLevel = 'debug' | 'info' | 'warn' | 'error'
+
+export interface DebugTraceEvent {
+  interactionId?: string
+  category: string
+  stage: string
+  level: DebugTraceLevel
+  sessionId?: string
+  providerType?: string
+  payload?: Record<string, unknown>
+}
+
+export interface DebugTraceEntry extends DebugTraceEvent {
+  id: string
+  ts: number
+}
+
+export interface DebugTraceStoreOptions {
+  enabled: boolean
+  capacity: number
+}
+
+export interface DebugTraceQuery {
+  interactionId?: string
+  category?: string
+  limit?: number
+}
+
+export interface DebugTraceStore {
+  record(event: DebugTraceEvent): DebugTraceEntry | null
+  list(query?: DebugTraceQuery): DebugTraceEntry[]
+  clear(): void
+}
+
+function summarizeString(value: string): string {
+  return `[${value.length} chars]`
+}
+
+function sanitizeTraceValue(value: unknown, traceContent: boolean): unknown {
+  if (traceContent) {
+    if (Array.isArray(value)) return value.map((entry) => sanitizeTraceValue(entry, traceContent))
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value as Record<string, unknown>).map(([key, nested]) => [key, sanitizeTraceValue(nested, traceContent)]),
+      )
+    }
+    return value
+  }
+
+  if (typeof value === 'string') return summarizeString(value)
+  if (Array.isArray(value)) return value.map((entry) => sanitizeTraceValue(entry, traceContent))
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, nested]) => [key, sanitizeTraceValue(nested, traceContent)]),
+    )
+  }
+  return value
+}
+
+export function sanitizeTracePayload(payload?: Record<string, unknown>): Record<string, unknown> {
+  if (!payload) return {}
+  const { traceContent } = getDebugRuntimeConfig()
+  return sanitizeTraceValue(payload, traceContent) as Record<string, unknown>
+}
+
+function createEntry(event: DebugTraceEvent): DebugTraceEntry {
+  return {
+    id: `trace_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+    ts: Date.now(),
+    ...event,
+    payload: sanitizeTracePayload(event.payload),
+  }
+}
+
+export function createDebugTraceStore(options: DebugTraceStoreOptions): DebugTraceStore {
+  const entries: DebugTraceEntry[] = []
+  const capacity = Math.max(1, Math.floor(options.capacity || 100))
+
+  return {
+    record(event: DebugTraceEvent): DebugTraceEntry | null {
+      if (!options.enabled) return null
+      const entry = createEntry(event)
+      entries.push(entry)
+      if (entries.length > capacity) {
+        entries.splice(0, entries.length - capacity)
+      }
+      return entry
+    },
+    list(query: DebugTraceQuery = {}): DebugTraceEntry[] {
+      const limit = Math.max(1, Math.floor(query.limit || 100))
+      return entries
+        .filter((entry) => !query.interactionId || entry.interactionId === query.interactionId)
+        .filter((entry) => !query.category || entry.category === query.category)
+        .slice(-limit)
+        .map((entry) => ({ ...entry, payload: entry.payload ? { ...entry.payload } : {} }))
+    },
+    clear(): void {
+      entries.splice(0, entries.length)
+    },
+  }
+}
+
+let globalStore = createDebugTraceStore({ enabled: false, capacity: getDebugRuntimeConfig().traceBufferSize })
+
+export function configureDebugTraceStore(): void {
+  const config = getDebugRuntimeConfig()
+  globalStore = createDebugTraceStore({
+    enabled: config.collectDebugTrace,
+    capacity: config.traceBufferSize,
+  })
+}
+
+export function recordDebugTrace(event: DebugTraceEvent): DebugTraceEntry | null {
+  if (!shouldCollectTraceCategory(event.category)) return null
+  return globalStore.record(event)
+}
+
+export function getRecentDebugTrace(query: DebugTraceQuery = {}): DebugTraceEntry[] {
+  return globalStore.list(query)
+}
+
+export function clearDebugTrace(): void {
+  globalStore.clear()
+}
+
+export function createInteractionId(prefix = 'ix'): string {
+  return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
+}

package/src/session-host/app-name.ts

@@ -0,0 +1,15 @@
+export const DEFAULT_SESSION_HOST_APP_NAME = 'adhdev'
+export const DEFAULT_STANDALONE_SESSION_HOST_APP_NAME = 'adhdev-standalone'
+
+export function resolveSessionHostAppName(options: {
+  standalone?: boolean
+  env?: NodeJS.ProcessEnv
+} = {}): string {
+  const env = options.env || process.env
+  const explicit = typeof env.ADHDEV_SESSION_HOST_NAME === 'string'
+    ? env.ADHDEV_SESSION_HOST_NAME.trim()
+    : ''
+
+  if (explicit) return explicit
+  return options.standalone ? DEFAULT_STANDALONE_SESSION_HOST_APP_NAME : DEFAULT_SESSION_HOST_APP_NAME
+}

package/src/shared-types.ts

@@ -187,6 +187,7 @@ export interface SessionChatTailUpdate extends ReadChatSyncResult {
     key: string;
     sessionId: string;
     historySessionId?: string;
+    interactionId?: string;
     seq: number;
     timestamp: number;
 }
@@ -215,6 +216,7 @@ export interface SessionModalUpdate {
     title?: string;
     modalMessage?: string;
     modalButtons?: string[];
+    interactionId?: string;
     seq: number;
     timestamp: number;
 }