@synergenius/flow-weaver-pack-weaver 0.9.7 → 0.9.9

package/src/bot/assistant-core.ts

@@ -23,6 +23,17 @@ import { VERBOSE_TOOL_NAMES } from './tool-registry.js';
 import { generateToolPromptSection, generateVerboseToolList } from './tool-registry.js';
 import { CHARS_PER_TOKEN } from './safety.js';
 
+export interface AssistantDebugTurn {
+  turn: number;
+  input: string;
+  toolCalls: Array<{ name: string; args: Record<string, unknown>; result: string; isError: boolean }>;
+  response: string;
+  tokensUsed: number;
+  systemPromptLength: number;
+  insightNudge?: string;
+  conversationId: string;
+}
+
 export interface AssistantOptions {
   provider: AgentProvider;
   tools: ToolDefinition[];
@@ -37,42 +48,75 @@ export interface AssistantOptions {
   resumeId?: string;
   /** Always start a fresh conversation */
   newConversation?: boolean;
+  /** Debug mode: output structured NDJSON per turn, no ANSI, full conversation loop */
+  debug?: boolean;
 }
 
-const DEFAULT_SYSTEM_PROMPT = `You are Weaver Assistant — a director-level AI that manages bot workers and the flow-weaver ecosystem.
+const DEFAULT_SYSTEM_PROMPT = `You are Weaver — a hands-on AI assistant for Flow Weaver projects.
+
+You help people build, validate, debug, and manage workflows. You can also spawn autonomous bot workers that execute tasks in the background.
+
+## What you do
+
+Tell me what you want to build or fix. I will:
+1. Break it into steps
+2. Use tools to read, write, validate, and test code
+3. Spawn bots for longer tasks that run in the background
+4. Track project health and surface insights proactively
+5. Propose bot workflow improvements based on execution patterns
+6. Report results — not plans
+
+## How to respond
 
-You help users with the following tools (grouped by category):
+Be direct and helpful. Adapt to the user — explain more for beginners, less for experts.
+When someone asks "what can you do", give a SHORT overview (5-6 lines max), not an exhaustive list. Mention /help for the full reference.
+
+USE TOOLS to fulfill requests. Don't describe what you'd do — do it.
+When asked to start a bot, call bot_spawn. For status, call bot_list. For tasks, call queue_add.
+
+## Available tools
 
 ${generateToolPromptSection()}
-USE TOOLS to fulfill requests. Don't describe what you'd do — actually do it.
-When the user asks to "start a bot", call bot_spawn.
-When they ask for status, call bot_list or bot_status.
-When they ask to add tasks, call queue_add or queue_add_batch.
-
-Be concise. Show results, not explanations.
-The user is a senior engineer — don't over-explain.
-
-CRITICAL: You are running in a terminal. Do NOT use markdown formatting.
-- No **bold**, no _italic_, no \`backticks\`, no tables with |pipes|
-- No emoji (✅, 🔴, etc.)
-- Use plain text with indentation for structure
-- Use UPPERCASE or quotes for emphasis instead of markdown
-- For lists, use simple dashes: - item
-- For key-value pairs, use: key: value (one per line)
-- Keep output scannable and clean
-
-IMPORTANT: Some tool results are displayed DIRECTLY to the user in the terminal.
-These tools show FULL output — the user already sees everything:
+
+## Terminal output rules
+
+You are running in a terminal. Plain text only.
+- No markdown: no **bold**, \`backticks\`, or |tables|
+- No emoji
+- Use plain dashes for lists, UPPERCASE or "quotes" for emphasis
+- Keep responses concise and scannable
+
+## Tool output handling
+
+CRITICAL: These tools display their FULL output directly to the user:
   ${generateVerboseToolList()}
-For these: do NOT repeat, summarize, or reformat the output. Just add a brief comment if needed.
-Never re-type ASCII art, diagrams, or large text blocks that were already printed.
+The user ALREADY SEES the complete output from these tools. After calling them:
+- Do NOT list, enumerate, or walk through the output
+- Do NOT restate what the diagram/description shows
+- ONLY add a brief insight the user cannot see (e.g. "Notice the fan-out at step 5 — that's where parallelism happens")
+- If the output speaks for itself, say nothing or just "There it is."
+For all other tools, you may explain the result briefly.
 
-Other tools show only a short preview.
-For those: you may summarize or explain the result as needed.`;
+## Personality
+
+- Helpful, practical, no fluff
+- Lead with the RESULT, not narration of what you did. Never start with "Let me...", "Found it.", "Now let me...", "Good, I have..."
+- If something fails, say what went wrong and what you'll try next
+- Never apologize for tool usage — tools are how you work
+- When you don't know something, say so
+
+## Project intelligence
+
+You have access to project health, bot performance, failure patterns, cost trends, and evolution history.
+Be proactive: when you see something relevant to what the user is doing, mention it.
+At session start, briefly acknowledge the project state if there's something worth noting.
+You can propose workflow improvements with genesis_propose when patterns suggest a structural fix.
+If a bot workflow needs modification and isn't ejected yet, auto-eject it first.`;
 
 
 export async function runAssistant(opts: AssistantOptions): Promise<void> {
   const { provider, tools, executor, projectDir } = opts;
+  const isDebug = !!opts.debug;
   const out = (s: string) => process.stderr.write(s);
 
   // Pipe mode: if stdin is not a TTY, read all input as one message
@@ -82,7 +126,10 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
       chunks.push(typeof chunk === 'string' ? chunk : chunk.toString());
     }
     const pipeInput = chunks.join('').trim();
-    if (!pipeInput) return;
+    if (!pipeInput) {
+      process.stderr.write('  No input provided. Pipe a message: echo "describe my workflows" | flow-weaver weaver assistant\n');
+      return;
+    }
 
     // Build system prompt for pipe mode
     let systemPrompt = opts.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
@@ -96,13 +143,23 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
       }
     } catch { /* plan not available */ }
 
+    // Inject project intelligence (ambient awareness)
+    try {
+      const { ProjectModelStore } = await import('./project-model.js');
+      const pms = new ProjectModelStore(projectDir);
+      const model = await pms.getOrBuild();
+      if (model && (model.health.workflows.length > 0 || model.bots.length > 0)) {
+        systemPrompt += '\n\n## Project Intelligence\n\n' + pms.formatSummary(model);
+      }
+    } catch { /* project model not available yet */ }
+
     // Run single message, print result, exit
     await runAgentLoop(provider, tools, executor, [{ role: 'user', content: pipeInput }], {
       systemPrompt, maxIterations: 20,
       onStreamEvent: (e) => { if (e.type === 'text_delta') out(e.text); },
       onToolEvent: (e) => {
         if (e.type === 'tool_call_start') out(`\n  ${c.cyan('◆')} ${e.name}\n`);
-        if (e.type === 'tool_call_result') out(`  ${c.dim('→')} ${(e.result ?? '').slice(0, 200)}\n`);
+        if (e.type === 'tool_call_result') out(`  ${c.dim('→')} ${(e.result ?? '').slice(0, 500)}\n`);
       },
     });
     out('\n');
@@ -121,12 +178,87 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
     }
   } catch { /* plan not available */ }
 
+  // Load steering configuration
+  let steeringEngine: import('./steering-engine.js').SteeringEngine | undefined;
+  try {
+    const { SteeringEngine, loadSteers } = await import('./steering-engine.js');
+    const steers = loadSteers(projectDir);
+    steeringEngine = new SteeringEngine(steers);
+  } catch { /* steering not available */ }
+
+  // Inject project intelligence (ambient awareness)
+  try {
+    const { ProjectModelStore } = await import('./project-model.js');
+    const pms = new ProjectModelStore(projectDir);
+    const model = await pms.getOrBuild();
+    if (model && (model.health.workflows.length > 0 || model.bots.length > 0)) {
+      systemPrompt += '\n\n## Project Intelligence\n\n' + pms.formatSummary(model);
+    }
+  } catch { /* project model not available yet */ }
+
+  // Auto-context scan: on first-ever use, scan project and persist context in knowledge store
+  try {
+    const { KnowledgeStore } = await import('./knowledge-store.js');
+    const knowledge = new KnowledgeStore(projectDir);
+    const existing = knowledge.recall('project:context');
+    if (existing.length === 0) {
+      // First-ever scan — build project context
+      const fsMod = await import('node:fs');
+      const parts: string[] = [];
+
+      // Package info
+      const pkgPath = path.join(projectDir, 'package.json');
+      if (fsMod.existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(fsMod.readFileSync(pkgPath, 'utf-8'));
+          parts.push(`Project: ${pkg.name ?? 'unknown'} v${pkg.version ?? '0.0.0'}`);
+          if (pkg.description) parts.push(`Description: ${pkg.description}`);
+          const deps = Object.keys(pkg.dependencies ?? {}).slice(0, 10);
+          if (deps.length > 0) parts.push(`Key deps: ${deps.join(', ')}`);
+        } catch { /* parse failed */ }
+      }
+
+      // Workflow scan
+      try {
+        const { execFileSync: scanExec } = await import('node:child_process');
+        const found = scanExec('npx', ['flow-weaver', 'find-workflows', '--json'], {
+          encoding: 'utf-8', cwd: projectDir, timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const workflows = JSON.parse(found);
+        if (Array.isArray(workflows) && workflows.length > 0) {
+          parts.push(`Workflows (${workflows.length}): ${workflows.map((w: { name?: string; file?: string }) => w.name ?? w.file ?? 'unknown').join(', ')}`);
+        }
+      } catch { /* find-workflows failed */ }
+
+      // TypeScript config
+      const tsConfigPath = path.join(projectDir, 'tsconfig.json');
+      if (fsMod.existsSync(tsConfigPath)) parts.push('TypeScript: yes');
+
+      // Weaver config
+      const weaverConfigPath = path.join(projectDir, '.weaver.json');
+      if (fsMod.existsSync(weaverConfigPath)) {
+        try {
+          const wc = JSON.parse(fsMod.readFileSync(weaverConfigPath, 'utf-8'));
+          parts.push(`Weaver provider: ${typeof wc.provider === 'string' ? wc.provider : wc.provider?.name ?? 'auto'}`);
+        } catch { /* parse failed */ }
+      }
+
+      if (parts.length > 0) {
+        knowledge.learn('project:context', parts.join('\n'), 'auto-scan');
+        systemPrompt += '\n\n## Project Context (auto-scanned)\n\n' + parts.join('\n');
+      }
+    } else {
+      // Context already scanned — inject from knowledge store
+      systemPrompt += '\n\n## Project Context\n\n' + existing[0]!.value;
+    }
+  } catch { /* knowledge store not available */ }
+
   // Persistent conversation store
   const { ConversationStore } = await import('./conversation-store.js');
   const store = new ConversationStore();
 
   // Resolve conversation: resume, new, or auto
-  let conversation: { id: string; title: string; messageCount: number };
+  let conversation: { id: string; title: string; messageCount: number; lastMessageAt: number };
   const history: AgentMessage[] = [];
 
   if (opts.resumeId) {
@@ -139,7 +271,7 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
     history.push(...store.loadMessages(existing.id));
     compressHistory(history);
   } else if (opts.newConversation) {
-    conversation = store.create(projectDir);
+    conversation = await store.create(projectDir);
   } else {
     // Auto-resume most recent if within 1 hour, else create new
     const recent = store.getMostRecent();
@@ -148,7 +280,7 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
       history.push(...store.loadMessages(recent.id));
       compressHistory(history);
     } else {
-      conversation = store.create(projectDir);
+      conversation = await store.create(projectDir);
     }
   }
 
@@ -162,22 +294,107 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
   try {
     const fsMod = await import('node:fs');
     const url = await import('node:url');
-    const packPkg = JSON.parse(fsMod.readFileSync(new url.URL('../package.json', import.meta.url), 'utf-8'));
+    const packPkg = JSON.parse(fsMod.readFileSync(new url.URL('../../package.json', import.meta.url), 'utf-8'));
     weaverVersion = packPkg.version;
   } catch { /* not available */ }
 
-  // Welcome
-  out(`\n  ${c.bold('weaver assistant')} ${c.dim(`v${weaverVersion}`)}  ${c.dim(`· flow-weaver v${fwVersion}`)}\n`);
-  if (process.env.FW_PLATFORM_TOKEN) {
-    out(`  ${c.dim('AI: Platform credits (no API key needed)')}\n`);
+  // Welcome — detect cloud status from credentials
+  let cloudStatus = '';
+  let cloudPlan = '';
+  try {
+    const credPath = path.join(os.homedir(), '.fw', 'credentials.json');
+    const fsMod = await import('node:fs');
+    if (fsMod.existsSync(credPath)) {
+      const creds = JSON.parse(fsMod.readFileSync(credPath, 'utf-8'));
+      if (creds.token && creds.expiresAt > Date.now()) {
+        cloudPlan = creds.plan ?? 'connected';
+        cloudStatus = `Cloud: ${cloudPlan}`;
+      } else if (creds.token) {
+        cloudStatus = 'Cloud: expired (run "fw login" to refresh)';
+      }
+    }
+  } catch { /* credentials not available */ }
+
+  // Detect first-run: scan for existing workflows and conversation count
+  let workflowCount = 0;
+  let projectName = path.basename(projectDir);
+  let packageDesc = '';
+  let isFirstRun = !conversation.title;
+  try {
+    const fsMod = await import('node:fs');
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (fsMod.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fsMod.readFileSync(pkgPath, 'utf-8'));
+      projectName = pkg.name ?? projectName;
+      packageDesc = pkg.description ?? '';
+    }
+    const { execFileSync: fwExec } = await import('node:child_process');
+    try {
+      const found = fwExec('npx', ['flow-weaver', 'find-workflows', '--json'], {
+        encoding: 'utf-8', cwd: projectDir, timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const parsed = JSON.parse(found);
+      workflowCount = Array.isArray(parsed) ? parsed.length : (parsed.count ?? 0);
+    } catch { /* find-workflows not available */ }
+  } catch { /* scan failed */ }
+
+  if (!isDebug) {
+    const header = [`weaver assistant v${weaverVersion}`, `flow-weaver v${fwVersion}`];
+    if (cloudStatus) header.push(cloudStatus);
+    out(`\n  ${c.bold(header[0])}  ${c.dim(`· ${header.slice(1).join('  · ')}`)}\n`);
+    out(`  ${c.dim(`Project: ${projectName}`)}\n`);
+    if (!cloudStatus) {
+      out(`  ${c.dim('AI: Local (set ANTHROPIC_API_KEY or run "fw login" to connect)')}\n`);
+    }
+    if (conversation.title) {
+      const ago = Math.round((Date.now() - conversation.lastMessageAt) / 60000);
+      out(`  ${c.dim(`Resuming: "${conversation.title}" (${conversation.messageCount} messages, ${ago}m ago). /new to start fresh`)}\n`);
+    } else if (workflowCount === 0 && isFirstRun) {
+      out(`  ${c.dim('Welcome! No workflows found yet.')}\n`);
+      out(`  ${c.dim('Try: "create a hello world workflow" or "what can you do?"')}\n`);
+    } else if (workflowCount > 0 && isFirstRun) {
+      out(`  ${c.dim(`Found ${workflowCount} workflow${workflowCount !== 1 ? 's' : ''}. New conversation.`)}\n`);
+      out(`  ${c.dim('Try: "validate my workflows" or "show project health"')}\n`);
+    } else {
+      out(`  ${c.dim('Type your request. /help for commands.')}\n`);
+    }
+    out('\n');
   }
-  out(`  ${c.dim(`Project: ${path.basename(projectDir)}`)}\n`);
-  if (conversation.title) {
-    out(`  ${c.dim(`Resuming: "${conversation.title}" (${conversation.messageCount} messages)`)}\n`);
-  } else {
-    out(`  ${c.dim(`New conversation`)}\n`);
+
+  // Proactive session greeting with project status (for returning users with data)
+  if (!isDebug && !isFirstRun) {
+    try {
+      const { ProjectModelStore } = await import('./project-model.js');
+      const pms = new ProjectModelStore(projectDir);
+      const model = await pms.getOrBuild();
+      if (model && (model.health.workflows.length > 0 || model.bots.length > 0)) {
+        out(`  ${c.dim(pms.formatSessionGreeting(model))}\n`);
+      }
+    } catch { /* project model not available yet */ }
+  }
+
+  // Check for updates (cached, max once per 24h, non-blocking)
+  if (!isDebug) {
+    try {
+      const { checkForUpdates, formatUpdateNotification } = await import('./update-checker.js');
+      const updates = await checkForUpdates(projectDir);
+      const notification = formatUpdateNotification(updates);
+      if (notification) {
+        out(`  ${c.yellow('⬆')} ${c.dim(notification.split('\n')[0]!)}\n`);
+        systemPrompt += `\n\n## Update Available\n\n${notification}\nMention this to the user if relevant.`;
+      }
+    } catch { /* update check failed — non-fatal */ }
+  }
+
+  // Inject first-run context into system prompt so the assistant adapts
+  if (workflowCount === 0 && isFirstRun) {
+    systemPrompt += '\n\n## First-Run Context\n\nThis is a NEW user with NO workflows yet. Be welcoming. Suggest creating their first workflow. If they describe what they want to build, offer to create it immediately. Do NOT assume they know Flow Weaver concepts — explain briefly as you go.';
+    if (packageDesc) {
+      systemPrompt += `\nProject description: "${packageDesc}". Use this to suggest a relevant first workflow.`;
+    }
+  } else if (workflowCount > 0 && isFirstRun) {
+    systemPrompt += `\n\n## First Conversation Context\n\nThis user has ${workflowCount} existing workflow${workflowCount !== 1 ? 's' : ''} but this is their first conversation with you. Offer to validate, describe, or improve their workflows. Be helpful but don't assume they're a beginner.`;
   }
-  out(`  ${c.dim('Type your request. Ctrl+C to exit. /help for commands.')}\n\n`);
 
   // Rich input with history, arrows, tab completion, slash commands
   const { RichInput } = await import('./rich-input.js');
@@ -200,29 +417,70 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
       })()
     : (): Promise<string | null> => richInput!.getInput();
 
+  // Debug mode: collect tool calls and response text per turn
+  let debugToolCalls: Array<{ name: string; args: Record<string, unknown>; result: string; isError: boolean }> = [];
+  const debugStreamToolNames = new Map<string, string>(); // id -> name for CLI provider tool tracking
+  let debugResponseText = '';
+  let debugInsightNudge: string | undefined;
+  let debugTurnCount = 0;
+
+  let lastStreamType = '';
   const onStreamEvent = (event: StreamEvent) => {
     if (event.type === 'text_delta') {
-      out(event.text);
+      if (lastStreamType === 'thinking_delta' && !isDebug) out('\n\n');
+      if (isDebug) { debugResponseText += event.text; }
+      else { out(event.text); }
     } else if (event.type === 'thinking_delta') {
-      out(c.dim(event.text));
+      if (!isDebug) out(c.dim(event.text));
     }
+    // Capture tool events from stream (CLI provider handles tools via MCP,
+    // so onToolEvent never fires — we catch them here instead)
+    if (isDebug) {
+      const e = event as Record<string, unknown>;
+      if (event.type === 'tool_use_start') {
+        debugStreamToolNames.set(String(e.id), String(e.name));
+      }
+      if (event.type === 'tool_result') {
+        debugToolCalls.push({
+          name: debugStreamToolNames.get(String(e.id)) ?? 'unknown',
+          args: {},
+          result: String(e.result ?? '').slice(0, 2000),
+          isError: !!e.isError,
+        });
+      }
+    }
+    lastStreamType = event.type;
   };
 
+  let currentToolName = '';
+  let currentToolArgs: Record<string, unknown> = {};
   const onToolEvent = (event: { type: string; name: string; args?: Record<string, unknown>; result?: string; isError?: boolean }) => {
     if (event.type === 'tool_call_start') {
-      const preview = toolPreview(event.name, event.args ?? {});
-      out(`\n  ${c.cyan('◆')} ${event.name}${preview ? c.dim(`(${preview})`) : ''}\n`);
+      currentToolName = event.name;
+      currentToolArgs = event.args ?? {};
+      if (!isDebug) {
+        const preview = toolPreview(event.name, event.args ?? {});
+        out(`\n  ${c.cyan('◆')} ${event.name}${preview ? c.dim(`(${preview})`) : ''}\n`);
+      }
     }
     if (event.type === 'tool_call_result') {
-      const icon = event.isError ? c.red('✗') : c.dim('→');
-      const raw = event.result ?? '';
-      // Show full output for diagram/describe/docs tools; truncate others
-      const isVerboseTool = VERBOSE_TOOL_NAMES.has(event.name);
-      if (isVerboseTool && raw.length > 150) {
-        out(`  ${icon}\n${raw}\n`);
+      if (isDebug) {
+        debugToolCalls.push({
+          name: currentToolName,
+          args: currentToolArgs,
+          result: (event.result ?? '').slice(0, 2000),
+          isError: !!event.isError,
+        });
       } else {
-        const result = raw.replace(/\n/g, ' ').slice(0, 200);
-        out(`  ${icon} ${result}\n`);
+        const icon = event.isError ? c.red('✗') : c.dim('→');
+        const raw = event.result ?? '';
+        const isVerboseTool = VERBOSE_TOOL_NAMES.has(event.name);
+        if (isVerboseTool && raw.length > 150) {
+          out(`  ${icon}\n${raw}\n`);
+        } else {
+          const result = raw.replace(/\n/g, ' ').slice(0, 200);
+          out(`  ${icon} ${result}\n`);
+        }
       }
     }
   };
@@ -236,7 +494,7 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
     conversationId: conversation.id,
     onClear: () => { history.length = 0; },
     onExit: () => { shouldExit = true; },
-    onNew: () => { history.length = 0; conversation = store.create(projectDir); },
+    onNew: async () => { history.length = 0; conversation = await store.create(projectDir); },
     onVerbose: () => { out(`  ${c.dim('Verbose toggling not yet wired to streaming.')}\n`); },
   };
 
@@ -256,7 +514,7 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
           const parsed = JSON.parse(result);
           const errorCount = parsed.errorCount ?? parsed.errors?.length ?? 0;
           if (errorCount > 0) {
-            out(`\n  ${c.yellow('⚠')} ${filename} changed: ${errorCount} validation error(s)\n`);
+            out(`\n  ${c.yellow('⚠')} ${opts.watchDir}/${filename}: ${errorCount} validation error(s). Ask me to fix them.\n`);
             out(`  ${c.dim('Type a message to fix, or ignore.')}\n`);
           }
         } catch { /* validation failed or not a workflow — ignore */ }
@@ -265,6 +523,9 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
     } catch { /* watch not available */ }
   }
 
+  // Track which insights have been nudged (by ID) to avoid repetition
+  const nudgedInsightIds = new Set<string>();
+
   // Main conversation loop
   while (!shouldExit) {
     const input = await getNextInput();
@@ -273,10 +534,29 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
 
     // Handle slash commands
     if (input.startsWith('/')) {
-      const handled = await handleSlashCommand(input, slashCtx);
-      if (handled) continue;
-      // Unknown slash command — tell user
-      out(`  ${c.dim('Unknown command. Type /help for available commands.')}\n\n`);
+      if (isDebug) {
+        // Capture slash command output for debug JSON
+        let slashOutput = '';
+        const debugSlashCtx = { ...slashCtx, out: (s: string) => { slashOutput += s; } };
+        const handled = await handleSlashCommand(input, debugSlashCtx);
+        if (handled) {
+          debugTurnCount++;
+          // Strip ANSI codes for clean debug output
+          const clean = slashOutput.replace(/\x1b\[[0-9;]*m/g, '').trim();
+          process.stdout.write(JSON.stringify({
+            turn: debugTurnCount,
+            input,
+            slashCommand: true,
+            response: clean,
+            conversationId: conversation.id,
+          }) + '\n');
+          continue;
+        }
+      } else {
+        const handled = await handleSlashCommand(input, slashCtx);
+        if (handled) continue;
+      }
+      if (!isDebug) out(`  ${c.dim('Unknown command. Type /help for available commands.')}\n\n`);
       continue;
     }
 
@@ -334,20 +614,97 @@ export async function runAssistant(opts: AssistantOptions): Promise<void> {
       // Token-aware compression
       compressHistory(history);
 
+      // Proactive insight surfacing — update system prompt for next turn
+      // Max 3 nudges per session to avoid being annoying
+      if (nudgedInsightIds.size < 3) {
+        try {
+          const { ProjectModelStore } = await import('./project-model.js');
+          const { InsightEngine } = await import('./insight-engine.js');
+          const pms = new ProjectModelStore(projectDir);
+          const model = await pms.getOrBuild();
+          const engine = new InsightEngine();
+          const insights = engine.analyze(model).filter(i => i.confidence >= 0.6);
+
+          if (insights.length > 0) {
+            // Skip insights already nudged (by ID) or mentioned in conversation
+            const unsurfaced = insights.filter(insight =>
+              !nudgedInsightIds.has(insight.id) &&
+              !history.some(m =>
+                m.role === 'assistant' &&
+                typeof m.content === 'string' &&
+                m.content.includes(insight.title)
+              )
+            );
+            if (unsurfaced.length > 0) {
+              const top = unsurfaced[0]!;
+              nudgedInsightIds.add(top.id);
+              const nudge = `\n\n[PROACTIVE CONTEXT: ${top.title}. ${top.description}${top.suggestion ? ` Suggestion: ${top.suggestion}` : ''}. Mention this naturally if relevant, or bring it up if there's a lull.]`;
+              if (isDebug) debugInsightNudge = nudge;
+              if (!systemPrompt.includes('[PROACTIVE CONTEXT:')) {
+                systemPrompt += nudge;
+              } else {
+                systemPrompt = systemPrompt.replace(/\n\n\[PROACTIVE CONTEXT:.*\]/s, nudge);
+              }
+            } else {
+              // Remove stale nudge from system prompt
+              systemPrompt = systemPrompt.replace(/\n\n\[PROACTIVE CONTEXT:.*\]/s, '');
+            }
+          }
+        } catch { /* insights not available */ }
+      }
+
+      // Check steering engine for time/event-based nudges
+      if (steeringEngine) {
+        const steerMsg = steeringEngine.check();
+        if (steerMsg) {
+          // Append to system prompt for next turn
+          if (systemPrompt.includes('[STEER') || systemPrompt.includes('[CONTEXT NOTE]') || systemPrompt.includes('[URGENT STEER]')) {
+            systemPrompt = systemPrompt.replace(/\n\n\[(CONTEXT NOTE|STEER|URGENT STEER)\].*$/s, '\n\n' + steerMsg);
+          } else {
+            systemPrompt += '\n\n' + steerMsg;
+          }
+        }
+      }
+
+      // Debug mode: emit structured NDJSON per turn
+      if (isDebug) {
+        debugTurnCount++;
+        const debugOutput: AssistantDebugTurn = {
+          turn: debugTurnCount,
+          input,
+          toolCalls: debugToolCalls,
+          response: debugResponseText,
+          tokensUsed,
+          systemPromptLength: systemPrompt.length,
+          insightNudge: debugInsightNudge,
+          conversationId: conversation.id,
+        };
+        process.stdout.write(JSON.stringify(debugOutput) + '\n');
+        // Reset for next turn
+        debugToolCalls = [];
+        debugStreamToolNames.clear();
+        debugResponseText = '';
+        debugInsightNudge = undefined;
+      }
+
       if (!result.success && result.summary) {
-        out(`\n  ${c.red(result.summary)}\n`);
+        if (!isDebug) out(`\n  ${c.red(result.summary)}\n`);
       }
     } catch (err: unknown) {
       const msg = err instanceof Error ? err.message : String(err);
-      out(`\n  ${c.red('Error:')} ${msg}\n`);
+      if (isDebug) {
+        process.stdout.write(JSON.stringify({ turn: ++debugTurnCount, error: msg, conversationId: conversation.id }) + '\n');
+      } else {
+        out(`\n  ${c.red('Error:')} ${msg}\n`);
+      }
     }
 
-    out('\n');
+    if (!isDebug) out('\n');
   }
 
   watcher?.close();
   richInput?.destroy();
-  out(`\n  ${c.dim('Goodbye.')}\n\n`);
+  if (!isDebug) out(`\n  ${c.dim('Goodbye.')}\n\n`);
 }
 
 function toolPreview(name: string, args: Record<string, unknown>): string {