@thispointon/kondi-chat 0.1.2

package/src/cli/submit.ts

@@ -0,0 +1,539 @@
+/**
+ * Agent submit handler — runs a user message through the loop.
+ *
+ * Extracted from backend.ts to shrink the god-object. The function has
+ * one closure-captured dependency (`emit` for pushing TUI events) which
+ * is now a named field on `SubmitDeps`. Everything else is passed in
+ * explicitly so this module can be tested without starting the full
+ * backend.
+ *
+ * Two entry paths:
+ *   1. @mention prefix ("@gpt write X") → single-shot call to a pinned
+ *      model, no agent loop.
+ *   2. Everything else → full agent loop with tool calls, compaction,
+ *      checkpoints, loop-guard-enforced caps, and optional autonomous
+ *      continuation when `opts.loop` is true (the /loop command).
+ */
+
+import { join } from 'node:path';
+import type { Session, LLMMessage, ProviderId, ToolCall } from '../types.ts';
+import type { ContextManager } from '../context/manager.ts';
+import type { Ledger } from '../audit/ledger.ts';
+import { estimateCost } from '../audit/ledger.ts';
+import type { Router as UnifiedRouter } from '../router/index.ts';
+import type { RoutingCollector } from '../router/collector.ts';
+import type { ToolContext } from '../engine/tools.ts';
+import type { ToolManager } from '../mcp/tool-manager.ts';
+import type { ProfileManager } from '../router/profiles.ts';
+import type { CheckpointManager } from '../engine/checkpoints.ts';
+import { callLLM } from '../providers/llm-caller.ts';
+import { LoopGuard } from '../engine/loop-guard.ts';
+import { isMutatingToolCall, predictedMutations } from '../engine/checkpoints.ts';
+import { detectCommands } from '../engine/verify.ts';
+import { compactInLoop, classifyPhase } from './submit-helpers.ts';
+import { classifyTaskLocal, frameProblem, type TaskClassification } from '../engine/task-router.ts';
+import { ReceiptStore, buildReceipt } from '../context/receipts.ts';
+import { assembleBrainContext } from '../context/project-brain.ts';
+
+export interface SubmitDeps {
+  session: Session;
+  contextManager: ContextManager;
+  ledger: Ledger;
+  router: UnifiedRouter;
+  collector: RoutingCollector;
+  toolCtx: ToolContext;
+  toolManager: ToolManager;
+  profiles: ProfileManager;
+  checkpointManager: CheckpointManager;
+  /** Push a live event back to the TUI. */
+  emit: (event: Record<string, unknown>) => void;
+}
+
+export interface SubmitOptions {
+  /** Autonomous-loop mode: keep iterating after "no tool calls" responses until DONE/STUCK or caps hit. */
+  loop?: boolean;
+  /** Goal text shown to the model during /loop continuation prompts. */
+  loopGoal?: string;
+}
+
+/** Short, human-readable tool-arg summary shown in TUI tool-call previews. */
+function formatToolArgs(tc: ToolCall): string {
+  const args = tc.arguments as Record<string, unknown>;
+  switch (tc.name) {
+    case 'read_file': return String(args.path || '');
+    case 'list_files': return String(args.path || '.');
+    case 'search_code': return `"${args.pattern}"`;
+    case 'run_command': return String(args.command || '').slice(0, 60);
+    case 'create_task': return String(args.description || '').slice(0, 60);
+    case 'update_plan': return args.goal ? `goal="${String(args.goal).slice(0, 40)}"` : '...';
+    default: return JSON.stringify(args).slice(0, 60);
+  }
+}
+
+export async function handleSubmit(
+  input: string,
+  deps: SubmitDeps,
+  opts?: SubmitOptions,
+): Promise<void> {
+  const {
+    session, contextManager, ledger, router, toolCtx, toolManager,
+    profiles, checkpointManager, emit,
+  } = deps;
+
+  const turnNumber = session.messages.filter(m => m.role === 'user').length + 1;
+  let checkpointCreated = false;
+  // Spec 08 — profile-driven bounds replace the old MAX_TOOL_ITERATIONS=20.
+  const loopGuard = new LoopGuard(profiles.getActive());
+  toolCtx.loopGuard = loopGuard;
+
+  // ── @mention path ───────────────────────────────────────────────────
+  const mentionMatch = input.match(/^@(\S+)\s+([\s\S]+)/);
+  if (mentionMatch) {
+    const alias = mentionMatch[1];
+    const message = mentionMatch[2];
+    const targetModel = router.registry.getByAlias(alias);
+    if (!targetModel) {
+      const candidates = router.registry.findAliasCandidates(alias);
+      const hint = candidates.length > 1
+        ? ` — ambiguous, could be: ${candidates.map(a => `@${a}`).join(', ')}`
+        : candidates.length === 0
+          ? ` — available: ${router.registry.getAliases().map(a => `@${a}`).join(', ')}`
+          : '';
+      emit({ type: 'error', message: `Unknown model: @${alias}${hint}` });
+      return;
+    }
+
+    contextManager.addUserMessage(input);
+    const { systemPrompt, userMessage, cacheablePrefix } = contextManager.assemblePrompt();
+    const msgId = `msg-${Date.now()}`;
+    emit({ type: 'message', id: msgId, role: 'assistant', content: '', model_label: targetModel.alias || targetModel.name });
+    emit({ type: 'status', text: `@${alias} ...` });
+
+    let streamedContent = '';
+    const response = await callLLM({
+      provider: targetModel.provider,
+      model: targetModel.id,
+      systemPrompt, userMessage,
+      maxOutputTokens: 8192, cacheablePrefix,
+      stream: true,
+      onToken: (token: string) => {
+        streamedContent += token;
+        emit({ type: 'message_update', id: msgId, content: streamedContent });
+      },
+    });
+
+    const cost = estimateCost(response.model, response.inputTokens, response.outputTokens);
+    contextManager.addAssistantMessage(response);
+    ledger.record('discuss', response, message.slice(0, 200));
+
+    emit({
+      type: 'message', id: msgId, role: 'assistant',
+      content: response.content,
+      model_label: targetModel.alias || targetModel.name,
+      reasoning_content: response.reasoningContent,
+    });
+    emit({
+      type: 'message_update', id: msgId, stats: {
+        input_tokens: response.inputTokens, output_tokens: response.outputTokens,
+        cost_usd: cost, models: [response.model], provider: targetModel.provider,
+        route_reason: `@${targetModel.alias}`, iterations: 1,
+      },
+    });
+    return;
+  }
+
+  // ── Task classification — fast local heuristic, no LLM call ────────
+  //
+  // The local classifier handles 95% of inputs instantly (regex + word
+  // count). Only genuinely ambiguous multi-sentence requests with broad
+  // verbs like "redesign" or "overhaul" fall through to the LLM classifier.
+  // This eliminates 2-5 seconds of latency on every single message.
+  const recentMessages = session.messages.slice(-4).map(m => `${m.role}: ${(m.content || '').slice(0, 200)}`).join('\n');
+  const taskClass = classifyTaskLocal(input, recentMessages);
+
+  // Handle frame_then_execute — frame the problem, show the frame, then
+  // run the agent loop against the framed goal instead of the raw input.
+  // Only triggered for broad multi-sentence requests with words like
+  // "redesign", "overhaul", etc. — very rare in practice.
+  let effectiveInput = input;
+  if (taskClass.mode === 'frame_then_execute') {
+    emit({ type: 'activity', text: `task-router: framing problem (${taskClass.reason})`, activity_type: 'step' });
+    try {
+      // Resolve cheapest model only when framing is actually needed.
+      const classifier = router.getClassifier();
+      let cheapProvider: ProviderId = classifier?.provider || 'anthropic';
+      let cheapModel: string | undefined = classifier?.model;
+      if (!classifier) {
+        const pinning = profiles.getActive().rolePinning;
+        if (pinning) {
+          const pinIds = new Set(Object.values(pinning));
+          const candidates = router.registry.getAvailable().filter(m => pinIds.has(m.id));
+          candidates.sort((a, b) => a.inputCostPer1M - b.inputCostPer1M);
+          cheapProvider = candidates[0]?.provider || 'anthropic';
+          cheapModel = candidates[0]?.id;
+        }
+      }
+      const frame = await frameProblem(input, '', cheapProvider, cheapModel);
+      emit({ type: 'activity', text: `frame: ${frame.interpretedGoal}`, activity_type: 'step' });
+      if (frame.successCriteria.length > 0) {
+        emit({ type: 'activity', text: `success: ${frame.successCriteria.join('; ')}`, activity_type: 'step' });
+      }
+      if (frame.proposedPlan.length > 0) {
+        emit({ type: 'activity', text: `plan: ${frame.proposedPlan.join(' → ')}`, activity_type: 'step' });
+      }
+      // Use the framed goal as the effective input for the agent loop.
+      effectiveInput = `${frame.interpretedGoal}\n\nSuccess criteria: ${frame.successCriteria.join('; ')}\n\nPlan: ${frame.proposedPlan.join('; ')}\n\nOriginal request: ${input}`;
+    } catch {
+      // If framing fails, proceed with the original input.
+      emit({ type: 'activity', text: 'task-router: framing failed, proceeding with original request', activity_type: 'step' });
+    }
+  } else {
+    emit({ type: 'activity', text: `task-router: ${taskClass.mode} (${taskClass.reason})`, activity_type: 'step' });
+  }
+
+  const workingDir = session.workingDirectory || process.cwd();
+  const storageDir = join(workingDir, '.kondi-chat');
+  const receipts = new ReceiptStore(storageDir, session.id);
+
+  // ── Project Brain: assemble all context (memory, receipts, skills, preflight) ──
+  // Skip preflight for short messages and follow-ups — the model has tools
+  // to read files when it needs them. Preflight only helps on substantive
+  // first-turn requests where it can save 2-3 tool calls.
+  const isFollowUp = turnNumber > 1 || effectiveInput.split(/\s+/).length < 10;
+  const brain = assembleBrainContext(workingDir, session, effectiveInput, { skipPreflight: isFollowUp });
+  if (brain.preflightFiles.length > 0) {
+    emit({ type: 'activity', text: `preflight: loaded ${brain.preflightFiles.join(', ')}`, activity_type: 'step' });
+  }
+  if (brain.skillsUsed.length > 0) {
+    emit({ type: 'activity', text: `skills: ${brain.skillsUsed.join(', ')}`, activity_type: 'step' });
+  }
+
+  // ── Regular agent loop ──────────────────────────────────────────────
+  contextManager.addUserMessage(effectiveInput);
+  const { systemPrompt: rawSystemPrompt, userMessage, cacheablePrefix } = contextManager.assemblePrompt();
+  // Inject brain context (memory + receipts + skills + preflight files).
+  const systemPrompt = brain.fullContext
+    ? `${rawSystemPrompt}\n\n${brain.fullContext}`
+    : rawSystemPrompt;
+  const messages: LLMMessage[] = [{ role: 'user', content: userMessage }];
+
+  // Resolve the post-edit typecheck command once per turn. Prefer the
+  // session-level repoMap (set by bootstrap), fall back to detecting from
+  // project files (handles TS/Python/Rust/Go). `null` means "no typecheck
+  // applies here, skip auto-verify silently" — much better than blindly
+  // running `tsc --noEmit` against a Python or Rust repo.
+  const autoVerifyCmd: string | null = (() => {
+    const fromRepoMap = session.repoMap?.commands?.typecheck;
+    if (fromRepoMap) return fromRepoMap;
+    const detected = detectCommands(workingDir).typecheck;
+    return detected ?? null;
+  })();
+
+  let totalInputTokens = 0, totalOutputTokens = 0, totalCost = 0;
+  let finalContent = '';
+  let respondingModel = '';
+  let respondingProvider = '';
+  let respondingReason = '';
+  const allToolCalls: Array<{ name: string; args: string; result: string; is_error: boolean; diff?: string }> = [];
+  const modelsUsed = new Set<string>();
+  const reasoningChunks: string[] = [];
+
+  const msgId = `msg-${Date.now()}`;
+  emit({ type: 'message', id: msgId, role: 'assistant', content: '', model_label: '...' });
+
+  // Dynamic phase: reclassified per iteration based on what the model
+  // is doing. Investigation (read/search) → dispatch (planning) →
+  // execute (write/edit) → reflect (review). The router selects a
+  // different model for each phase from the profile's rolePinning.
+  // This is how the agent switches models mid-turn automatically.
+  let currentPhase: import('../types.ts').LedgerPhase = classifyPhase(effectiveInput);
+  emit({
+    type: 'activity',
+    text: `router: phase=${currentPhase} (${currentPhase === 'execute' ? 'coding intent detected' : 'discussion / reasoning'})`,
+    activity_type: 'step',
+  });
+
+  while (true) {
+    const iteration = loopGuard.check().iteration;
+    const decision = await router.select(currentPhase, userMessage, undefined, iteration);
+    respondingModel = decision.model.alias || decision.model.name;
+    respondingProvider = decision.model.provider;
+    respondingReason = decision.reason;
+    emit({ type: 'status', text: `${respondingModel} thinking${iteration > 0 ? ` (step ${iteration + 1})` : ''}...` });
+    emit({
+      type: 'activity',
+      text: `→ ${respondingModel} (${decision.tier}: ${decision.reason})`,
+      activity_type: 'step',
+    });
+    emit({ type: 'message_update', id: msgId, model_label: respondingModel });
+
+    // Before each model call, enforce the profile's contextBudget by
+    // stubbing old tool results in place. No LLM calls — zero cost.
+    const budget = profiles.getActive().contextBudget;
+    const compaction = compactInLoop(messages, budget);
+    if (compaction.savedBytes > 0) {
+      emit({
+        type: 'activity',
+        text: `context: ${compaction.before.toLocaleString()} → ${compaction.after.toLocaleString()} tokens (${compaction.savedBytes.toLocaleString()} chars pruned)`,
+        activity_type: 'step',
+      });
+    }
+
+    let iterContent = '';
+    const response = await callLLM({
+      provider: decision.model.provider,
+      model: decision.model.id,
+      systemPrompt, messages,
+      tools: toolManager.getTools('discuss'),
+      maxOutputTokens: 8192, cacheablePrefix,
+      stream: true,
+      onToken: (token: string) => {
+        iterContent += token;
+        // Show accumulated content across ALL iterations, not just
+        // the current one. This prevents earlier text ("Step 3: ...")
+        // from vanishing when the model calls tools and starts a new
+        // iteration.
+        emit({ type: 'message_update', id: msgId, content: finalContent + iterContent });
+      },
+    });
+
+    // If the response came from a fallback model, update the label so the
+    // user sees which model actually responded, not just which was requested.
+    if (response.wasFallback) {
+      const fallbackAlias = router.registry.getById(response.model)?.alias || response.model;
+      respondingModel = `${respondingModel}→${fallbackAlias}`;
+      emit({ type: 'activity', text: `fallback: ${response.requestedModel || 'unknown'} failed, used ${response.model}`, activity_type: 'step' });
+      emit({ type: 'message_update', id: msgId, model_label: respondingModel });
+    }
+
+    const iterCost = estimateCost(response.model, response.inputTokens, response.outputTokens);
+    totalInputTokens += response.inputTokens;
+    totalOutputTokens += response.outputTokens;
+    totalCost += iterCost;
+    modelsUsed.add(response.model);
+
+    if (response.reasoningContent) {
+      const header = reasoningChunks.length === 0
+        ? `── ${response.model} ──`
+        : `\n── ${response.model} (step ${reasoningChunks.length + 1}) ──`;
+      reasoningChunks.push(`${header}\n${response.reasoningContent}`);
+    }
+
+    ledger.record('discuss', response, messages[messages.length - 1]?.content?.slice(0, 200) || '');
+
+    // Accumulate this iteration's text so it persists across iterations.
+    // Without this, "Step 3: ..." vanishes when the model calls tools.
+    if (response.content) {
+      finalContent += (finalContent ? '\n\n' : '') + response.content;
+    }
+
+    if (!response.toolCalls || response.toolCalls.length === 0) {
+      // Autonomous-loop mode: when the model stops calling tools but the
+      // goal isn't explicitly marked done, synthesize a "continue" prompt
+      // and keep iterating. LoopGuard still enforces hard caps.
+      if (opts?.loop) {
+        const body = (response.content || '').trim();
+        const terminated = /^DONE\b/mi.test(body) || /^STUCK\b/mi.test(body);
+        if (!terminated && !loopGuard.check().shouldStop) {
+          messages.push({ role: 'assistant', content: response.content || '(progress)' });
+          messages.push({
+            role: 'user',
+            content:
+              `Continue working on the goal: "${opts.loopGoal || input}".\n` +
+              `If the goal is fully accomplished, respond with DONE on its own line followed by a brief summary.\n` +
+              `If you are blocked and cannot proceed, respond with STUCK: <reason>.\n` +
+              `Otherwise keep going — call the tools you need.`,
+          });
+          emit({ type: 'activity', text: 'loop: continuing — no terminal marker', activity_type: 'step' });
+          continue;
+        }
+      }
+      // finalContent already accumulated above
+      break;
+    }
+
+    messages.push({
+      role: 'assistant',
+      content: response.content || undefined,
+      toolCalls: response.toolCalls,
+      reasoningContent: response.reasoningContent,
+    });
+
+    const toolResults = [];
+    for (const tc of response.toolCalls) {
+      const toolArgs = formatToolArgs(tc);
+      emit({ type: 'tool_call', name: tc.name, args: toolArgs, is_error: false });
+      emit({ type: 'activity', text: `${tc.name}(${toolArgs})`, activity_type: 'tool' });
+
+      // Spec 05 — create a checkpoint before the first mutating tool in this turn.
+      if (!checkpointCreated && isMutatingToolCall(tc.name, tc.arguments)) {
+        try {
+          const predicted = new Set([
+            ...(toolCtx.mutatedFiles ?? []),
+            ...predictedMutations(tc.name, tc.arguments),
+          ]);
+          checkpointManager.create(
+            `Turn ${turnNumber}: ${input.slice(0, 60)}`,
+            input,
+            turnNumber,
+            totalCost,
+            predicted,
+          );
+          checkpointCreated = true;
+        } catch (e) {
+          emit({ type: 'error', message: `Checkpoint failed: ${(e as Error).message}` });
+        }
+      }
+
+      const result = await toolManager.execute(tc.name, tc.arguments, toolCtx);
+
+      // Post-edit verification policy: after any file mutation, run the
+      // detected typecheck so the model sees compile errors immediately
+      // without needing to call run_command itself. Skipped entirely when
+      // the project has no typecheck (plain JS, Bash repo, etc.) — running
+      // `tsc` against a non-TS project produces noise and 30s waits.
+      if (autoVerifyCmd && isMutatingToolCall(tc.name, tc.arguments) && !result.isError) {
+        try {
+          const { execSync: execSyncVerify } = await import('node:child_process');
+          const verifyResult = execSyncVerify(autoVerifyCmd, {
+            cwd: workingDir,
+            encoding: 'utf-8',
+            timeout: 30_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+          }).trim();
+          if (verifyResult) {
+            result.content += `\n\n[auto-verify: ${verifyResult.includes('error') ? 'ISSUES FOUND' : 'clean'}]\n${verifyResult.slice(0, 500)}`;
+          }
+        } catch (verifyErr: any) {
+          const output = (verifyErr.stdout || verifyErr.stderr || verifyErr.message || '').toString().trim();
+          if (output) {
+            result.content += `\n\n[auto-verify: FAILED]\n${output.slice(0, 500)}`;
+          }
+        }
+      }
+
+      const capped = result.content.length > 3000 ? result.content.slice(0, 3000) + '...' : result.content;
+
+      allToolCalls.push({
+        name: tc.name,
+        args: toolArgs,
+        result: capped.slice(0, 300),
+        is_error: result.isError || false,
+        diff: result.diff,
+      });
+      emit({ type: 'message_update', id: msgId, content: response.content || '', tool_calls: [...allToolCalls] });
+
+      toolResults.push({ toolCallId: tc.id, content: capped, isError: result.isError, diff: result.diff });
+    }
+
+    messages.push({ role: 'tool', toolResults });
+
+    // Dynamic phase reclassification: based on what tools just ran,
+    // determine what the NEXT iteration should be. This is how the
+    // agent switches between models mid-turn — investigation uses the
+    // cheap/discuss model, coding uses the execute model, review uses
+    // the reflect model.
+    const toolsThisRound = new Set(response.toolCalls!.map(tc => tc.name));
+    const prevPhase: import('../types.ts').LedgerPhase = currentPhase;
+    if (toolsThisRound.has('write_file') || toolsThisRound.has('edit_file')) {
+      // Just wrote code → next iteration should review/reflect
+      currentPhase = 'reflect';
+    } else if (toolsThisRound.has('update_plan') || toolsThisRound.has('create_task')) {
+      // Just planned → next iteration should execute
+      currentPhase = 'execute';
+    } else if (toolsThisRound.has('read_file') || toolsThisRound.has('search_code') ||
+               toolsThisRound.has('find_symbol') || toolsThisRound.has('related_files') ||
+               toolsThisRound.has('repo_map')) {
+      // Just investigated → next iteration should plan/dispatch
+      currentPhase = 'dispatch';
+    } else if (toolsThisRound.has('run_command')) {
+      // Just ran a command (test/build) → reflect on results
+      currentPhase = 'reflect';
+    }
+    // else: keep current phase (e.g. for web_search, consult, etc.)
+
+    if (currentPhase !== prevPhase) {
+      emit({ type: 'activity', text: `phase: ${prevPhase} → ${currentPhase}`, activity_type: 'step' });
+    }
+
+    // Spec 08 — drive the loop with LoopGuard. Feed the first tool error so
+    // stuck detection works on ordinary turns.
+    const firstError = toolResults.find(r => r.isError)?.content;
+    loopGuard.recordIteration(iterCost, firstError);
+    const guard = loopGuard.check();
+    if (guard.shouldStop) {
+      // Give the model one final no-tools iteration to summarize what it
+      // found. This is the difference between "Loop stopped: iteration
+      // limit" with zero useful output and a real summary of progress.
+      try {
+        emit({ type: 'status', text: `${respondingModel} summarizing (cap reached)...` });
+        const finalResponse = await callLLM({
+          provider: decision.model.provider,
+          model: decision.model.id,
+          systemPrompt,
+          messages: [
+            ...messages,
+            { role: 'user', content: `You have reached the iteration limit (${guard.stopReason || 'bounds reached'}). Do not call any more tools. Summarize what you found, what you produced, and what remains to be done, in 10 lines or fewer.` },
+          ],
+          maxOutputTokens: 2048,
+          cacheablePrefix,
+        });
+        totalInputTokens += finalResponse.inputTokens;
+        totalOutputTokens += finalResponse.outputTokens;
+        totalCost += estimateCost(finalResponse.model, finalResponse.inputTokens, finalResponse.outputTokens);
+        finalContent = (finalResponse.content || response.content || '').trim()
+          + `\n\n_(loop stopped: ${guard.stopReason || 'bounds reached'})_`;
+      } catch {
+        finalContent = (response.content || `(no final output)`) + `\n\n_(loop stopped: ${guard.stopReason || 'bounds reached'})_`;
+      }
+      break;
+    }
+  }
+
+  // Append file modification summary
+  const filesModified = allToolCalls
+    .filter(tc => ['write_file', 'edit_file', 'create_task'].includes(tc.name) && !tc.is_error)
+    .map(tc => {
+      if (tc.name === 'create_task') return `  ✦ task: ${tc.args}`;
+      return `  ${tc.name === 'write_file' ? '+' : '~'} ${tc.args}`;
+    });
+  if (filesModified.length > 0) {
+    finalContent += '\n\nFiles:\n' + filesModified.join('\n');
+  }
+
+  contextManager.addAssistantMessage({
+    content: finalContent, model: respondingModel,
+    provider: 'openai' as ProviderId,
+    inputTokens: totalInputTokens, outputTokens: totalOutputTokens, latencyMs: 0,
+  });
+
+  emit({
+    type: 'message_update', id: msgId,
+    content: finalContent,
+    model_label: respondingModel,
+    tool_calls: allToolCalls.length > 0 ? allToolCalls : null,
+    reasoning_content: reasoningChunks.length > 0 ? reasoningChunks.join('\n') : undefined,
+    stats: {
+      input_tokens: totalInputTokens, output_tokens: totalOutputTokens,
+      cost_usd: totalCost, models: [...modelsUsed],
+      provider: respondingProvider,
+      route_reason: respondingReason,
+      iterations: messages.filter(m => m.role === 'assistant').length || 1,
+    },
+  });
+
+  emit({ type: 'status', text: '' });
+  toolCtx.permissionManager?.endTurn();
+
+  // Record a context receipt for cross-turn continuity.
+  receipts.record(buildReceipt(
+    turnNumber,
+    input.slice(0, 200),
+    respondingModel,
+    allToolCalls,
+    finalContent,
+  ));
+
+  await contextManager.maybeCompact();
+  await contextManager.updateSessionState();
+}

package/src/cli/wizard.ts

@@ -0,0 +1,121 @@
+/**
+ * First-run setup wizard.
+ *
+ * Called from the non-interactive path (or manually via `/wizard`). Writes a
+ * minimal `.kondi-chat/config.json` if one does not already exist, and notes
+ * which providers are likely configured based on environment variables.
+ *
+ * The wizard is non-interactive by default: it inspects the environment and
+ * writes sensible defaults without blocking. An interactive stdin path can be
+ * added later by a thin caller around this module.
+ */
+
+import { existsSync, writeFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export interface WizardResult {
+  configPath: string;
+  created: boolean;
+  providersDetected: string[];
+  defaultProfile: string;
+}
+
+const PROVIDER_ENV: Record<string, string> = {
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+  deepseek: 'DEEPSEEK_API_KEY',
+  google: 'GOOGLE_API_KEY',
+  xai: 'XAI_API_KEY',
+};
+
+export function runFirstRunWizard(storageDir: string, opts: { interactive?: boolean } = {}): WizardResult {
+  const configPath = join(storageDir, 'config.json');
+  const providersDetected = Object.entries(PROVIDER_ENV)
+    .filter(([, envVar]) => !!process.env[envVar])
+    .map(([id]) => id);
+
+  if (existsSync(configPath)) {
+    return { configPath, created: false, providersDetected, defaultProfile: readProfile(configPath) };
+  }
+
+  const defaultProfile: WizardResult['defaultProfile'] = providersDetected.length === 0
+    ? 'cheap'
+    : providersDetected.includes('anthropic') ? 'balanced' : 'balanced';
+
+  const config = {
+    defaultProfile,
+    providers: providersDetected,
+    createdAt: new Date().toISOString(),
+  };
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+  if (opts.interactive) {
+    process.stderr.write(`[wizard] wrote ${configPath}\n`);
+    process.stderr.write(`[wizard] detected providers: ${providersDetected.join(', ') || '(none — set an API key)'}\n`);
+  }
+
+  return { configPath, created: true, providersDetected, defaultProfile };
+}
+
+function readProfile(path: string): string {
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf-8'));
+    if (typeof raw.defaultProfile === 'string' && raw.defaultProfile.length > 0) {
+      return raw.defaultProfile;
+    }
+  } catch { /* ignore */ }
+  return 'balanced';
+}
+
+/** Persist the active profile name to config.json, preserving other fields. */
+export function writeActiveProfile(storageDir: string, name: string): void {
+  const configPath = join(storageDir, 'config.json');
+  let config: Record<string, unknown> = {};
+  try {
+    if (existsSync(configPath)) {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    }
+  } catch { /* start fresh on parse error */ }
+  config.defaultProfile = name;
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+
+/** Read the persisted active profile from config.json (or 'balanced'). */
+export function readActiveProfile(storageDir: string): string {
+  return readProfile(join(storageDir, 'config.json'));
+}
+
+/**
+ * Update-available banner. Fetches the latest release tag from GitHub, caches
+ * for 24 hours under ~/.kondi-chat/.update-check. Never blocks startup.
+ */
+export async function checkForUpdate(currentVersion: string): Promise<string | null> {
+  if (process.env.KONDI_NO_UPDATE_CHECK === '1') return null;
+  try {
+    const cachePath = join(process.env.HOME || '.', '.kondi-chat', '.update-check');
+    if (existsSync(cachePath)) {
+      const cached = JSON.parse(readFileSync(cachePath, 'utf-8')) as { checkedAt: number; latest: string };
+      if (Date.now() - cached.checkedAt < 24 * 60 * 60 * 1000) {
+        return cached.latest !== currentVersion ? banner(cached.latest) : null;
+      }
+    }
+    const resp = await fetch('https://api.github.com/repos/kondi/kondi-chat/releases/latest', {
+      signal: AbortSignal.timeout(3000),
+      headers: { 'Accept': 'application/vnd.github+json' },
+    });
+    if (!resp.ok) return null;
+    const data = await resp.json() as { tag_name?: string };
+    const latest = (data.tag_name || '').replace(/^v/, '');
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, JSON.stringify({ checkedAt: Date.now(), latest }));
+    return latest && latest !== currentVersion ? banner(latest) : null;
+  } catch {
+    return null;
+  }
+}
+
+function banner(latest: string): string {
+  return `Update available: kondi-chat ${latest} — run \`npm install -g kondi-chat@latest\` or \`brew upgrade kondi-chat\``;
+}