@thispointon/kondi-chat 0.1.2

package/src/engine/sub-agents.ts

@@ -0,0 +1,133 @@
+/**
+ * Sub-agent spawning — bounded child agent loops.
+ *
+ * This is a minimal implementation: each spawn runs an inline loop that
+ * calls callLLM + toolManager.execute on a filtered tool set. Parallelism
+ * is handled by the caller (the `spawn_agent` tool awaits one at a time in
+ * this version; Promise.all at the call site yields natural parallelism).
+ *
+ * Sub-agents do NOT nest (no recursive spawn_agent). Loop guard caps
+ * iterations and cost.
+ */
+
+import type { LLMMessage, ToolDefinition, Session } from '../types.ts';
+import type { Router } from '../router/index.ts';
+import type { ToolContext, ToolExecutionResult } from './tools.ts';
+import type { ToolManager } from '../mcp/tool-manager.ts';
+import { callLLM } from '../providers/llm-caller.ts';
+import { estimateCost } from '../audit/ledger.ts';
+
+export type SubAgentType = 'research' | 'worker' | 'planner';
+
+const MAX_SUB_ITERATIONS = 8;
+const MAX_SUB_COST_USD = 0.50;
+const MAX_RESULT_CHARS = 4000;
+
+const RESEARCH_TOOLS = new Set(['read_file', 'list_files', 'search_code', 'web_search', 'web_fetch', 'git_status', 'git_diff', 'git_log']);
+const WORKER_TOOLS = new Set<string>([
+  'read_file', 'list_files', 'search_code', 'write_file', 'edit_file', 'run_command',
+  'git_status', 'git_diff', 'git_log', 'git_commit',
+]);
+
+function filterToolsForType(type: SubAgentType, tools: ToolDefinition[]): ToolDefinition[] {
+  if (type === 'planner') return [];
+  const set = type === 'research' ? RESEARCH_TOOLS : WORKER_TOOLS;
+  return tools.filter(t => set.has(t.name));
+}
+
+function systemPromptForType(type: SubAgentType, parentGoal?: string): string {
+  const goalLine = parentGoal ? `Parent session goal: ${parentGoal}\n\n` : '';
+  if (type === 'planner') {
+    return `${goalLine}You are a planning sub-agent. Return a concise plan; do not call tools. Output a numbered list of concrete steps.`;
+  }
+  if (type === 'research') {
+    return `${goalLine}You are a research sub-agent. Gather information and return a concise summary. You may read files and search code but must not modify anything.`;
+  }
+  return `${goalLine}You are a worker sub-agent. Complete the given task. You may read, write, and edit files, and run commands. Return a short summary of what you did.`;
+}
+
+export interface SubAgentResult {
+  type: SubAgentType;
+  instruction: string;
+  finalContent: string;
+  iterations: number;
+  inputTokens: number;
+  outputTokens: number;
+  costUsd: number;
+  model: string;
+  error?: string;
+  truncated?: boolean;
+}
+
+export async function runSubAgent(
+  type: SubAgentType,
+  instruction: string,
+  parent: {
+    router: Router;
+    toolManager: ToolManager;
+    toolCtx: ToolContext;
+    session: Session;
+  },
+): Promise<SubAgentResult> {
+  const { router, toolManager, toolCtx, session } = parent;
+  const systemPrompt = systemPromptForType(type, session.state.goal);
+  const tools = filterToolsForType(type, toolManager.getTools('discuss'));
+
+  const messages: LLMMessage[] = [{ role: 'user', content: instruction }];
+  let inputTokens = 0, outputTokens = 0, costUsd = 0;
+  let finalContent = '';
+  let model = '';
+
+  for (let iter = 0; iter < MAX_SUB_ITERATIONS; iter++) {
+    const decision = await router.select(type === 'planner' ? 'dispatch' : type === 'research' ? 'discuss' : 'execute', instruction);
+    model = decision.model.alias || decision.model.name;
+    const response = await callLLM({
+      provider: decision.model.provider,
+      model: decision.model.id,
+      systemPrompt,
+      messages,
+      tools: tools.length > 0 ? tools : undefined,
+      maxOutputTokens: 4096,
+    });
+    inputTokens += response.inputTokens;
+    outputTokens += response.outputTokens;
+    costUsd += estimateCost(response.model, response.inputTokens, response.outputTokens);
+
+    if (costUsd > MAX_SUB_COST_USD) {
+      finalContent = response.content || 'sub-agent cost cap reached';
+      return {
+        type, instruction, finalContent, iterations: iter + 1,
+        inputTokens, outputTokens, costUsd, model, error: 'cost-cap',
+      };
+    }
+
+    if (!response.toolCalls || response.toolCalls.length === 0) {
+      finalContent = response.content;
+      return { type, instruction, finalContent, iterations: iter + 1, inputTokens, outputTokens, costUsd, model };
+    }
+
+    messages.push({ role: 'assistant', content: response.content || undefined, toolCalls: response.toolCalls });
+    const toolResults = [];
+    for (const tc of response.toolCalls) {
+      const result: ToolExecutionResult = await toolManager.execute(tc.name, tc.arguments, toolCtx);
+      const capped = result.content.length > 3000 ? result.content.slice(0, 3000) + '...' : result.content;
+      toolResults.push({ toolCallId: tc.id, content: capped, isError: result.isError });
+    }
+    messages.push({ role: 'tool', toolResults });
+  }
+
+  finalContent = finalContent || `sub-agent hit ${MAX_SUB_ITERATIONS} iterations without finishing`;
+  return {
+    type, instruction, finalContent: finalContent.slice(0, MAX_RESULT_CHARS),
+    iterations: MAX_SUB_ITERATIONS, inputTokens, outputTokens, costUsd, model,
+    error: 'max-iterations',
+    truncated: finalContent.length > MAX_RESULT_CHARS,
+  };
+}
+
+/** Formats a SubAgentResult as a short block suitable for the parent's tool_result content. */
+export function formatSubAgentResult(r: SubAgentResult): string {
+  const header = `[sub-agent ${r.type} via ${r.model}; ${r.iterations}it; $${r.costUsd.toFixed(4)}${r.error ? `; ${r.error}` : ''}]`;
+  const body = r.finalContent.length > MAX_RESULT_CHARS ? r.finalContent.slice(0, MAX_RESULT_CHARS) + '\n[truncated]' : r.finalContent;
+  return `${header}\n${body}`;
+}

package/src/engine/task-card.ts

@@ -0,0 +1,185 @@
+/**
+ * Task Card — bounded work packets dispatched to worker models.
+ *
+ * The task card is the contract between the conversation model and
+ * the execution model. It contains everything the worker needs and
+ * nothing it doesn't.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { TaskCard, TaskKind, RepoMap, SessionState, LLMResponse } from '../types.ts';
+import { callLLM } from '../providers/llm-caller.ts';
+import type { Ledger } from '../audit/ledger.ts';
+import type { ProviderId } from '../types.ts';
+
+// ---------------------------------------------------------------------------
+// Task Card creation — frontier model generates from conversation
+// ---------------------------------------------------------------------------
+
+export async function createTaskCard(
+  userIntent: string,
+  sessionState: SessionState,
+  repoMap: RepoMap | undefined,
+  provider: ProviderId,
+  model: string | undefined,
+  ledger: Ledger,
+): Promise<{ card: TaskCard; response: LLMResponse }> {
+
+  const repoContext = repoMap
+    ? `Stack: ${repoMap.stack.join(', ')}
+Subsystems: ${repoMap.subsystems.map(s => `${s.name} (${s.paths.join(', ')}): ${s.purpose}`).join('\n')}
+Entrypoints: ${repoMap.entrypoints.join(', ')}
+Commands: build=${repoMap.commands.build || 'n/a'} test=${repoMap.commands.test || 'n/a'} lint=${repoMap.commands.lint || 'n/a'}
+Conventions: ${repoMap.conventions.join('; ')}`
+    : '(no repo map available)';
+
+  const stateContext = `Goal: ${sessionState.goal || 'not set'}
+Plan: ${sessionState.currentPlan.join(' → ') || 'none'}
+Decisions: ${sessionState.decisions.join('; ') || 'none'}
+Constraints: ${sessionState.constraints.join('; ') || 'none'}
+Recent failures: ${sessionState.recentFailures.join('; ') || 'none'}`;
+
+  const response = await callLLM({
+    provider,
+    model,
+    systemPrompt: `You create structured task cards for a coding assistant. Output ONLY valid JSON.
+
+A task card is a bounded work packet with:
+- id: short identifier (e.g., "task-001")
+- kind: one of "implementation", "fix", "refactor", "test", "analysis"
+- goal: clear 1-2 sentence description of what to do
+- relevantFiles: array of file paths the worker should focus on
+- constraints: array of things NOT to do or boundaries
+- acceptanceCriteria: array of conditions that must be true when done
+- outputMode: "diff" for patches, "file_replacements" for full files, "text" for analysis
+
+Be specific and bounded. The worker model will ONLY see this card, not the conversation.`,
+    userMessage: `Create a task card for the following request.
+
+SESSION STATE:
+${stateContext}
+
+REPO:
+${repoContext}
+
+USER REQUEST:
+${userIntent}
+
+Output the task card as JSON:`,
+    maxOutputTokens: 1500,
+    temperature: 0,
+  });
+
+  ledger.record('dispatch', response, `Task card creation for: ${userIntent.slice(0, 200)}`);
+
+  let parsed: any = {};
+  try {
+    // Extract JSON from response — model may wrap it in markdown code blocks
+    const jsonMatch = response.content.match(/\{[\s\S]*\}/);
+    parsed = jsonMatch ? JSON.parse(jsonMatch[0]) : {};
+  } catch {
+    process.stderr.write(`[dispatch] Failed to parse task card JSON, using defaults\n`);
+  }
+
+  const card: TaskCard = {
+    id: parsed.id || `task-${Date.now().toString(36)}`,
+    kind: parsed.kind || 'implementation',
+    goal: parsed.goal || userIntent,
+    relevantFiles: parsed.relevantFiles || [],
+    constraints: parsed.constraints || [],
+    acceptanceCriteria: parsed.acceptanceCriteria || [],
+    outputMode: parsed.outputMode || 'file_replacements',
+    failures: 0,
+    createdAt: new Date().toISOString(),
+    status: 'pending',
+  };
+
+  return { card, response };
+}
+
+// ---------------------------------------------------------------------------
+// Task execution — worker model processes the card
+// ---------------------------------------------------------------------------
+
+export async function executeTaskCard(
+  card: TaskCard,
+  repoMap: RepoMap | undefined,
+  fileContents: string,
+  provider: ProviderId,
+  model: string | undefined,
+  ledger: Ledger,
+): Promise<LLMResponse> {
+
+  const taskPrompt = `TASK CARD:
+${JSON.stringify(card, null, 2)}
+
+RELEVANT FILE CONTENTS:
+${fileContents}`;
+
+  const systemPrompt = card.kind === 'analysis'
+    ? `You are a code analysis agent. Analyze the code as specified in the task card. Be thorough and specific. Reference exact files and line numbers.`
+    : `You are a code execution agent. Implement exactly what the task card specifies.
+
+Rules:
+- Only modify files listed in relevantFiles unless absolutely necessary
+- Respect all constraints
+- Output your changes as ${card.outputMode === 'diff' ? 'unified diffs' : 'complete file contents with clear path labels'}
+- When done, end with:
+  ## RESULT
+  **Status:** complete | partial
+  **Files changed:** list of files
+  **Notes:** anything the reviewer should know`;
+
+  const response = await callLLM({
+    provider,
+    model,
+    systemPrompt,
+    userMessage: taskPrompt,
+    maxOutputTokens: 8192,
+  });
+
+  ledger.record('execute', response, `Execute task ${card.id}: ${card.goal.slice(0, 200)}`, {
+    taskId: card.id,
+    promoted: card.failures >= 2,
+  });
+
+  return response;
+}
+
+// ---------------------------------------------------------------------------
+// Read relevant files for a task card
+// ---------------------------------------------------------------------------
+
+export function readRelevantFiles(
+  workingDir: string,
+  files: string[],
+  maxCharsPerFile = 4096,
+): string {
+  const base = resolve(workingDir);
+  const sections: string[] = [];
+
+  for (const relPath of files) {
+    const fullPath = join(workingDir, relPath);
+    const resolved = resolve(fullPath);
+
+    // Path traversal check
+    if (!resolved.startsWith(base)) continue;
+    if (!existsSync(fullPath)) {
+      sections.push(`#### ${relPath}\n(file not found)`);
+      continue;
+    }
+
+    try {
+      let content = readFileSync(fullPath, 'utf-8');
+      if (content.length > maxCharsPerFile) {
+        content = content.slice(0, maxCharsPerFile) + '\n... (truncated)';
+      }
+      sections.push(`#### ${relPath}\n\`\`\`\n${content}\n\`\`\``);
+    } catch {
+      sections.push(`#### ${relPath}\n(read error)`);
+    }
+  }
+
+  return sections.join('\n\n');
+}

package/src/engine/task-router.ts

@@ -0,0 +1,256 @@
+/**
+ * Task Router — adaptive problem framing before execution.
+ *
+ * Decides automatically whether a task is:
+ *   A. directly executable (concrete, unambiguous)
+ *   B. needs lightweight framing (broad but inferable)
+ *   C. needs user clarification (risky or ambiguous)
+ *   D. needs council/deeper deliberation (design tradeoffs)
+ *
+ * Runs a single cheap classifier call before the agent loop starts.
+ * The user never has to say "think first" or "define the problem" —
+ * kondi infers it from task shape.
+ */
+
+import type { ProviderId } from '../types.ts';
+import { callLLM } from '../providers/llm-caller.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type TaskMode =
+  | 'execute_now'
+  | 'frame_then_execute'
+  | 'ask_clarifying_question'
+  | 'council_deliberation';
+
+export interface TaskClassification {
+  mode: TaskMode;
+  confidence: number;
+  reason: string;
+  missingInformation: string[];
+  suggestedQuestions: string[];
+  executionGoal?: string;
+}
+
+export interface ProblemFrame {
+  originalRequest: string;
+  interpretedGoal: string;
+  whyThisMatters: string;
+  currentBehavior?: string;
+  desiredBehavior?: string;
+  constraints: string[];
+  assumptions: string[];
+  unknowns: string[];
+  successCriteria: string[];
+  proposedPlan: string[];
+  executionScope: 'small' | 'medium' | 'large';
+}
+
+// ---------------------------------------------------------------------------
+// Classifier
+// ---------------------------------------------------------------------------
+
+const CLASSIFY_PROMPT = `You classify user tasks for a coding agent. Based on the task, decide the mode:
+
+execute_now — the task is concrete and unambiguous. Examples: "fix this error", "rename this function", "add logging", "run tests", "read this file", "explain this code"
+
+frame_then_execute — the task is broad but you can infer what to do. Examples: "clean up the provider system", "improve the onboarding", "make this less confusing", "refactor the auth module"
+
+ask_clarifying_question — the task is risky or genuinely ambiguous, and acting without clarification could waste effort or cause harm. Examples: "change the auth flow" (which part?), "delete unused code" (what counts as unused?), "make it production ready" (what's the target?)
+
+council_deliberation — the task involves real design tradeoffs that benefit from multiple perspectives. Examples: "redesign the architecture", "choose between strategies", "plan the roadmap"
+
+Most tasks are execute_now. Only escalate when there's genuine ambiguity or risk. Simple questions and straightforward coding tasks are always execute_now.
+
+Respond with ONLY a JSON object:
+{"mode": "execute_now|frame_then_execute|ask_clarifying_question|council_deliberation", "confidence": 0.0-1.0, "reason": "one sentence", "missingInformation": [], "suggestedQuestions": [], "executionGoal": "optional refined goal"}`;
+
+/**
+ * Fast local classification — no LLM call. Handles 95% of inputs instantly.
+ * Only falls back to an LLM call for genuinely ambiguous cases where the
+ * heuristic has low confidence.
+ */
+export function classifyTaskLocal(
+  userRequest: string,
+  recentContext: string,
+): TaskClassification {
+  const lower = userRequest.toLowerCase().trim();
+  const wordCount = lower.split(/\s+/).length;
+
+  // Very short messages are always execute_now (greetings, "yes", "do it", etc.)
+  if (wordCount <= 6) {
+    return { mode: 'execute_now', confidence: 0.95, reason: 'short input', missingInformation: [], suggestedQuestions: [] };
+  }
+
+  // Follow-up messages in an ongoing conversation are always execute_now
+  if (recentContext.length > 50) {
+    return { mode: 'execute_now', confidence: 0.9, reason: 'follow-up in conversation', missingInformation: [], suggestedQuestions: [] };
+  }
+
+  // Direct action verbs → execute_now
+  const actionVerbs = /^(fix|add|create|write|read|show|list|run|test|build|deploy|install|update|change|rename|remove|delete|explain|refactor|implement|move|copy|find|search|check|debug|log|print|open|close|merge|revert|commit|push|pull)\b/i;
+  if (actionVerbs.test(lower)) {
+    return { mode: 'execute_now', confidence: 0.9, reason: 'action verb', missingInformation: [], suggestedQuestions: [] };
+  }
+
+  // Questions → execute_now (the model will answer)
+  if (lower.startsWith('what') || lower.startsWith('how') || lower.startsWith('why') ||
+      lower.startsWith('where') || lower.startsWith('when') || lower.startsWith('can') ||
+      lower.startsWith('does') || lower.startsWith('is ') || lower.endsWith('?')) {
+    return { mode: 'execute_now', confidence: 0.9, reason: 'question', missingInformation: [], suggestedQuestions: [] };
+  }
+
+  // File references → execute_now
+  if (/\.(ts|js|py|rs|go|json|yml|yaml|toml|md|css|html|sql)\b/.test(lower)) {
+    return { mode: 'execute_now', confidence: 0.9, reason: 'file reference', missingInformation: [], suggestedQuestions: [] };
+  }
+
+  // Broad/vague multi-sentence requests with no concrete target → frame_then_execute
+  const broadIndicators = /\b(redesign|overhaul|rethink|architect|migrate|strategy|roadmap|plan out)\b/i;
+  if (broadIndicators.test(lower) && wordCount > 15) {
+    return { mode: 'frame_then_execute', confidence: 0.7, reason: 'broad request', missingInformation: [], suggestedQuestions: [] };
+  }
+
+  // Default: execute_now. The model itself is good at asking for
+  // clarification when it needs it — we don't need a pre-classifier.
+  return { mode: 'execute_now', confidence: 0.8, reason: 'default', missingInformation: [], suggestedQuestions: [] };
+}
+
+/**
+ * LLM-based classification — only called when the local heuristic has
+ * low confidence. Most inputs never reach this.
+ */
+export async function classifyTask(
+  userRequest: string,
+  recentContext: string,
+  classifierProvider: ProviderId,
+  classifierModel?: string,
+): Promise<TaskClassification> {
+  // Fast path: local heuristic handles 95% of inputs with no LLM call.
+  const local = classifyTaskLocal(userRequest, recentContext);
+  if (local.confidence >= 0.7) return local;
+
+  try {
+    const response = await callLLM({
+      provider: classifierProvider,
+      model: classifierModel,
+      systemPrompt: CLASSIFY_PROMPT,
+      userMessage: `Task: ${userRequest.slice(0, 1500)}${recentContext ? `\n\nRecent context: ${recentContext.slice(0, 500)}` : ''}`,
+      maxOutputTokens: 200,
+      temperature: 0,
+    });
+
+    const text = response.content.trim();
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      return { mode: 'execute_now', confidence: 0.5, reason: 'classifier returned non-JSON', missingInformation: [], suggestedQuestions: [] };
+    }
+
+    const parsed = JSON.parse(jsonMatch[0]);
+    return {
+      mode: parsed.mode || 'execute_now',
+      confidence: parsed.confidence ?? 0.8,
+      reason: parsed.reason || '',
+      missingInformation: parsed.missingInformation || [],
+      suggestedQuestions: parsed.suggestedQuestions || [],
+      executionGoal: parsed.executionGoal,
+    };
+  } catch {
+    // If classification fails, default to execute — don't block the user.
+    return { mode: 'execute_now', confidence: 0.5, reason: 'classifier error — defaulting to execute', missingInformation: [], suggestedQuestions: [] };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Problem Framer
+// ---------------------------------------------------------------------------
+
+const FRAME_PROMPT = `You are a problem framing assistant for a coding agent. The user gave a broad task. Your job is to:
+
+1. Interpret what they actually want
+2. Define clear success criteria
+3. Propose a concrete plan
+
+Be concise. No filler. Output ONLY a JSON object:
+{
+  "interpretedGoal": "what the user really wants",
+  "whyThisMatters": "one sentence on why",
+  "currentBehavior": "what happens now (if known)",
+  "desiredBehavior": "what should happen after",
+  "constraints": ["things to preserve or avoid"],
+  "assumptions": ["things you're assuming"],
+  "unknowns": ["things you'd need to verify"],
+  "successCriteria": ["how to know it's done"],
+  "proposedPlan": ["step 1", "step 2", ...],
+  "executionScope": "small|medium|large"
+}`;
+
+export async function frameProblem(
+  userRequest: string,
+  recentContext: string,
+  provider: ProviderId,
+  model?: string,
+): Promise<ProblemFrame> {
+  const response = await callLLM({
+    provider,
+    model,
+    systemPrompt: FRAME_PROMPT,
+    userMessage: `Task: ${userRequest}\n\n${recentContext ? `Context: ${recentContext.slice(0, 1000)}` : ''}`,
+    maxOutputTokens: 800,
+    temperature: 0,
+  });
+
+  const text = response.content.trim();
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) {
+    return {
+      originalRequest: userRequest,
+      interpretedGoal: userRequest,
+      whyThisMatters: '',
+      constraints: [],
+      assumptions: [],
+      unknowns: [],
+      successCriteria: [],
+      proposedPlan: [userRequest],
+      executionScope: 'medium',
+    };
+  }
+
+  const parsed = JSON.parse(jsonMatch[0]);
+  return {
+    originalRequest: userRequest,
+    interpretedGoal: parsed.interpretedGoal || userRequest,
+    whyThisMatters: parsed.whyThisMatters || '',
+    currentBehavior: parsed.currentBehavior,
+    desiredBehavior: parsed.desiredBehavior,
+    constraints: parsed.constraints || [],
+    assumptions: parsed.assumptions || [],
+    unknowns: parsed.unknowns || [],
+    successCriteria: parsed.successCriteria || [],
+    proposedPlan: parsed.proposedPlan || [],
+    executionScope: parsed.executionScope || 'medium',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Frame formatter (for TUI display)
+// ---------------------------------------------------------------------------
+
+export function formatFrame(frame: ProblemFrame): string {
+  const lines: string[] = [
+    `Goal: ${frame.interpretedGoal}`,
+  ];
+  if (frame.whyThisMatters) lines.push(`Why: ${frame.whyThisMatters}`);
+  if (frame.currentBehavior) lines.push(`Now: ${frame.currentBehavior}`);
+  if (frame.desiredBehavior) lines.push(`Target: ${frame.desiredBehavior}`);
+  if (frame.successCriteria.length > 0) {
+    lines.push(`Success: ${frame.successCriteria.join('; ')}`);
+  }
+  if (frame.proposedPlan.length > 0) {
+    lines.push(`Plan: ${frame.proposedPlan.map((s, i) => `${i + 1}. ${s}`).join(' → ')}`);
+  }
+  lines.push(`Scope: ${frame.executionScope}`);
+  return lines.join('\n');
+}

package/src/engine/task-store.ts

@@ -0,0 +1,86 @@
+/**
+ * Task Store — persists task cards to disk so they survive session
+ * restarts. Active tasks are injected into context so the model
+ * knows what it was working on.
+ *
+ * Storage:
+ *   .kondi-chat/tasks/current.json — the active task (if any)
+ *   .kondi-chat/tasks/history/     — completed tasks
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import type { TaskCard } from '../types.ts';
+
+export class TaskStore {
+  private tasksDir: string;
+  private currentPath: string;
+  private historyDir: string;
+
+  constructor(storageDir: string) {
+    this.tasksDir = join(storageDir, 'tasks');
+    this.currentPath = join(this.tasksDir, 'current.json');
+    this.historyDir = join(this.tasksDir, 'history');
+    mkdirSync(this.historyDir, { recursive: true });
+  }
+
+  /** Get the active task, if any. */
+  getCurrent(): TaskCard | null {
+    if (!existsSync(this.currentPath)) return null;
+    try {
+      return JSON.parse(readFileSync(this.currentPath, 'utf-8'));
+    } catch {
+      return null;
+    }
+  }
+
+  /** Save or update the active task. */
+  setCurrent(task: TaskCard): void {
+    writeFileSync(this.currentPath, JSON.stringify(task, null, 2));
+  }
+
+  /** Move the active task to history (completed or abandoned). */
+  complete(): void {
+    const task = this.getCurrent();
+    if (!task) return;
+    const historyPath = join(this.historyDir, `${task.id}.json`);
+    try {
+      renameSync(this.currentPath, historyPath);
+    } catch {
+      // If rename fails, just delete current
+      try { writeFileSync(this.currentPath, ''); } catch { /* ignore */ }
+    }
+  }
+
+  /** Clear the active task without archiving. */
+  clear(): void {
+    if (existsSync(this.currentPath)) {
+      try { writeFileSync(this.currentPath, ''); } catch { /* ignore */ }
+    }
+  }
+
+  /** Format active task for injection into context. */
+  formatForContext(): string {
+    const task = this.getCurrent();
+    if (!task) return '';
+    const lines = [
+      '## Active task',
+      `Goal: ${task.goal}`,
+      `Kind: ${task.kind}`,
+      `Status: ${task.status}`,
+    ];
+    if (task.relevantFiles.length > 0) {
+      lines.push(`Files: ${task.relevantFiles.join(', ')}`);
+    }
+    if (task.constraints.length > 0) {
+      lines.push(`Constraints: ${task.constraints.join('; ')}`);
+    }
+    if (task.acceptanceCriteria.length > 0) {
+      lines.push(`Acceptance: ${task.acceptanceCriteria.join('; ')}`);
+    }
+    if (task.failures > 0) {
+      lines.push(`Failures: ${task.failures}`);
+    }
+    return lines.join('\n');
+  }
+}